155 lines
9.8 KiB
Markdown
155 lines
9.8 KiB
Markdown
# 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<T>` 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<T>` / `IOptionsMonitor<T>` 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.
|