# VigilCareClinical Technology & Technique Guides A breakdown of all distinct technologies and techniques used across VigilCareClinical, organized as standalone guide topics. --- ## Infrastructure & DevOps ### 1. Docker Compose for Multi-Service Orchestration Profiles, health checks, `extra_hosts`, service dependency ordering, and selective startup for local development of a 10+ service stack. ### 2. Prometheus + Grafana Monitoring Stack Custom metric families (counters, histograms, gauges), third-party collectors, dashboard provisioning, scrape configuration, and alerting on clinical safety metrics. ### 3. Structured Logging with Serilog + Seq Enrichers (correlation ID, machine name, thread ID), multiple sinks (console, Seq), structured property filtering, and centralized log search for distributed services. ### Gitea CI/CD with Docker Compose Local vs production Compose split, multi-stage Dockerfiles, `.env` on the deploy host (not in CD), Gitea Actions CI (deps + tests) and CD (registry push, migrations, SSH deploy, smoke test, tag rollback). Full walkthrough: [`docs/guides/25-gitea-cicd-docker-deploy.md`](guides/25-gitea-cicd-docker-deploy.md). --- ## Data Layer ### 4. PostgreSQL with Entity Framework Core Migrations (40+), JSONB columns for flexible schema, partial unique indexes for idempotency, sequences for MRN generation, connection pooling, and transactional guarantees for domain consistency. ### 5. Redis as Clinical State Store Sliding window TTLs for scoring criteria, cache-aside pattern for thresholds, pre-loading on startup with retry backoff, distributed state aggregation across encounter-scoped keys, and suppression key management. ### 6. Apache Kafka Event Streaming KRaft mode (no Zookeeper), explicit topic provisioning with 6 partitions, 9 consumer groups, idempotent producers, offset management for partial-commit safety, and poison pill guards for permanent vs transient error handling. ### 7. RabbitMQ for Notification Queuing Topology provisioning on startup, dead-letter queues with TTL-based retry backoff, acknowledgment timeouts for paging workflows, graceful in-flight message requeuing on shutdown, and connection pooling via factory pattern. ### 8. Elasticsearch as a CQRS Read Store Index provisioning with mapping definitions, upsert semantics for patient/encounter documents, append-only observation indices, aggregation queries for alert analytics, and health check integration. ### 9. MinIO Data Lake with Parquet S3-compatible object storage, date-partitioned Parquet file generation, partial-commit safety (Kafka offset committed only when all uploads succeed), and partition/offset lineage for audit trails. --- ## Architecture Patterns ### 10. Transactional Outbox Pattern Outbox table co-committed with domain entities, relay service polling with `FOR UPDATE SKIP LOCKED`, idempotent Kafka production, retry tracking with error capture, and safe concurrent relay instances. ### 11. CQRS (Command Query Responsibility Segregation) PostgreSQL as the write store, Elasticsearch as the read store, Kafka consumers bridging the two, denormalized document projections, and eventual consistency guarantees. ### 12. Event-Driven Background Services in .NET `IHostedService` lifecycle management, scoped service factories for DI in singletons, concurrent consumer design, graceful shutdown with cancellation tokens, and startup ordering for provisioners. --- ## Security & Authentication ### 13. JWT Authentication in ASP.NET Core Token generation with claims (user ID, role, IP), HMAC-SHA256 signing with 256-bit minimum key enforcement, issuer/audience validation, configurable expiration, and `JwtBearer` middleware pipeline. ### 14. Role-Based Access Control (RBAC) with Dynamic Policies Four roles (Nurse, Physician, Admin, Integration), 18 granular permissions, `PermissionPolicyProvider` for dynamic policy resolution, `PermissionAuthorizationHandler` with Prometheus failure tracking, and `[AuthorizePermission]` attribute on every controller action. ### 15. API Key Authentication for Machine-to-Machine `X-Api-Key` + `X-Gateway-Id` header scheme, constant-time comparison via `CryptographicOperations.FixedTimeEquals`, dual auth middleware (API key OR JWT), and key rotation support via array-based validation. ### 16. PHI Encryption with Data Protection API Column-level encryption at rest in PostgreSQL, DPAPI protector with versioned purpose string, HMAC search tokens for encrypted field lookups, key path configuration, and one-time migration service for existing plaintext data. ### 17. Password Hashing with BCrypt `BCrypt.Net-Next` with configurable cost factor (default 12), no plaintext storage, and integration with the clinical user authentication flow. --- ## API Design ### 18. REST API Design & Conventions Standard envelope response (`{ success, statusCode, data, error }`), HTTP method semantics (GET/POST/PATCH), cursor-based (keyset) pagination with base64-encoded cursors, `Idempotency-Key` header support, and field-level validation error details. ### 19. FHIR R4 Integration Facade Inbound resource endpoints (Patient, Encounter, Observation, MedicationAdministration), transaction bundle processing with dependency ordering, LOINC/SNOMED code mapping, CapabilityStatement metadata, OperationOutcome error responses, external identifier resolution, and unit conversion. ### 20. OpenAPI/Swagger Documentation Swashbuckle setup with Bearer JWT security scheme, XML documentation comments on public APIs, development-only endpoint exposure, and auto-generated API specification. ### 21. Input Validation with FluentValidation `AbstractValidator` implementations for all request DTOs, auto-validation on model binding, assembly scanning for validator registration, and custom clinical plausibility rules (observation code bounds, value ranges). --- ## Clinical Domain Engines ### 22. Clinical Scoring Engines (NEWS2, GCS, SOFA, qSOFA) Kafka-driven scoring pipelines consuming `observation.recorded` and `gcs.scored` topics, Redis state aggregation with encounter-scoped TTLs, baseline establishment and delta calculation (SOFA), consciousness resolution (GCS-first with AVPU fallback for NEWS2), stale lab handling with carry-forward, and multi-level alert generation. ### 23. Sepsis Bundle Automation SOFA delta >= 2 triggers automatic bundle creation, four mandatory elements (blood cultures, lactate, antibiotics, IV fluids), auto-created orders, 1-hour compliance deadline, monitor service scanning every 5 minutes, idempotent one-bundle-per-encounter constraint, and atomic transactional creation. ### 24. Trend Detection (Rate-of-Change Analysis) Velocity calculation (change/minute) using Redis sliding windows, configurable time windows and per-parameter thresholds, five vital sign parameters tracked, `RAPID_DETERIORATION` alert generation, and Kafka consumer-based architecture. ### 25. Alert Lifecycle & Suppression Synchronous critical alert creation within observation ingest, asynchronous warning evaluation via Kafka, acknowledgment-triggered Redis suppression keys with configurable TTL, escalation path (paging -> DLQ -> on-call backup), and never-suppress rules for critical alerts. --- ## Frontend ### 26. Vue 3 + Vite SPA Architecture Composition API, Vite 8 for fast dev server and production bundling, project structure conventions, and route-based code organization. ### 27. Pinia State Management Store design with actions calling REST APIs, reactive state with computed getters, modular stores per domain (alerts, auth, scoring, sepsis, operations, ward), and integration with Vue Router. ### 28. Tailwind CSS for Clinical UIs Custom severity color palette (critical, warning, info), status colors (open, acknowledged, resolved, escalated), risk level theming (low, medium, high), dark mode support via class strategy, and `@tailwindcss/vite` plugin. ### 29. Chart.js with vue-chartjs for Clinical Data Visualization Line graphs for vital sign trends, bar charts for alert volume analytics, gauge-style charts for composite scores (SOFA, NEWS2), and score history timelines (GCS, qSOFA evaluation). --- ## Testing ### 30. Integration Testing with WebApplicationFactory In-memory test server (no Docker required), custom `TestingAuthHandler` for role-based test auth, `ApiFixture` for shared database/Kafka/Redis setup, database seeding per test run, and `ClearAuth()` before role assignment pattern. ### 31. Frontend Testing with Vitest jsdom browser DOM simulation, test files in `src/__tests__/`, mock utilities, snapshot testing, and coverage reporting with Vite-native configuration. --- ## Tooling ### 32. Console Replay Simulator `System.CommandLine` CLI with subcommands (replay, replay-all, validate, dry-run), speed multipliers (0 = instant, 60 = 60x), live polling for alert/score state during replay, Spectre.Console rich output formatting, and JSON scenario file format. ### 33. End-to-End Verification Scripts 32 shell scripts for phase-specific pipeline testing, docker-compose lifecycle management, simulator-driven scenario execution, API query assertions, and full stack validation. --- ## Cross-Cutting Concerns ### 34. Configuration via Options Pattern Strongly-typed configuration classes (`JwtOptions`, `KafkaOptions`, etc.), environment-specific overrides (Development, Testing), `IOptions` / `IOptionsMonitor` injection, and centralized `appsettings.json` management. ### 35. Health Check Endpoints Liveness (`/health/live`) vs readiness (`/health/ready`) probe separation, per-dependency checks (PostgreSQL, Redis, Kafka, RabbitMQ, Elasticsearch), JSON response with status and duration per check, and Kubernetes/load balancer integration. ### 36. Ward Gateway Edge Architecture Offline observation buffering with sync-on-reconnect, heartbeat reporting with buffer depth, stale detection auto-marking gateways OFFLINE, encounter replica sync from central API, batch upload with JWT authentication, and degraded operations visibility.