Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
163 lines (99 loc) · 8.24 KB

DEPLOYMENT.md

File metadata and controls

163 lines (99 loc) · 8.24 KB
Raw

Halkyone Clinical OS: Deployment & Production Strategy

Halkyone Clinical OS is engineered for high-availability clinical environments. This document outlines the architectural readiness, DevOps strategy, and recommended production infrastructure for scaling the platform to enterprise-grade operations.

🏗️ Architectural Readiness

The codebase leverages Clean Architecture, CQRS (MediatR), and Domain-Driven Design (DDD), making it inherently stable and maintainable for production use.

Key Strengths

  • Decoupled Services: The GraphQL API (HotChocolate) and Next.js frontend are completely independent, allowing for separate scaling and deployment cycles.
  • Reproducible Environments: Full Dockerization via docker-compose ensures development, staging, and production parity.
  • Validated Integrity: Integrated CI/CD pipelines (ci.yml) with xUnit (Backend) and Playwright (Frontend) ensure that every build is mission-ready.

🚀 DevOps Strategy

The "Easy" Path

  • CI/CD Integration: Automated testing and build validation via GitHub Actions.
  • Independent Scaling: The frontend and backend can be scaled horizontally to meet demand.
  • Containerization: Ready for orchestration platforms like Kubernetes or Azure Container Apps.

Critical Considerations (Hardening)

  • SignalR Scaling: Live patient telemetry (WebSockets) requires a dedicated strategy. In a multi-instance environment, sticky sessions or a Redis backplane are mandatory to prevent connection drops.
  • Database Migrations: Multi-tenant migrations must be staged carefully to avoid table locking during clinical operations.

☁️ Recommended Infrastructure: Microsoft Azure

Microsoft Azure is the unequivocally superior choice for this stack, providing native, managed services for .NET, SignalR, and SQL.

1. Backend: Azure Container Apps

Push the Dockerized .NET 9 API to Azure Container Apps.

  • Scaling: Auto-scales based on traffic (can scale to zero to minimize costs).
  • Security: Native SSL management and automated health checks.

2. Live Telemetry: Azure SignalR Service

Offload WebSocket management to the fully managed Azure SignalR Service.

  • High Throughput: Handles thousands of simultaneous patient telemetry connections.
  • Reliability: Removes the burden of connection state management from the application servers.

3. Database: Azure SQL (Serverless)

Utilize the multi-tenant architecture with Azure SQL Database.

  • Compliance: Built-in Transparent Data Encryption (TDE) for HIPAA and local healthcare data privacy compliance.
  • Efficiency: The Serverless tier auto-pauses during low-usage hours and scales instantly during peak hospital shifts.

4. Frontend: Vercel or Azure Static Web Apps

  • Option A (Vercel): Best-in-class Next.js hosting with global Edge distribution and PWA optimization.
  • Option B (Azure Static Web Apps): Ideal for unified compliance and billing within the Azure ecosystem.

5. Secure Storage: Azure Blob Storage

Patient records and medical documentation should be stored in Azure Blob Storage.

  • Encryption: Encrypted at rest.
  • Access Control: Utilize Shared Access Signatures (SAS) for temporary, secure file access.

🔍 Granular Infrastructure Deep-Dive

1. Why Azure Container Apps?

In clinical settings, traffic is highly variable.

  • Scale-to-Zero: Horizontal Pod Autoscaling (HPA) allows the backend to scale down entirely during off-peak hours (e.g., 3 AM), drastically reducing compute costs without sacrificing availability.
  • Immutable Deployments: Dockerization ensures that the exact environment used in development is mirrored in production, eliminating configuration drift.

2. The SignalR "Backplane" Problem

In a multi-instance production environment, standard SignalR connections are stored in a server's local memory. If a patient connects to Server A and a clinician to Server B, they cannot see each other.

  • The Azure Fix: The Azure SignalR Service acts as a global switchboard, handling all WebSocket handshakes externally. This ensures real-time telemetry synchronization regardless of which backend instance a user hits.

3. Azure SQL: Serverless & TDE

  • TDE (Transparent Data Encryption): Mandatory for healthcare audits. It encrypts the physical database files (.mdf/.ldf) at rest, ensuring data is unreadable even if the storage medium is compromised.
  • Serverless Efficiency: Automatically adjusts CPU and Memory based on clinical workload (e.g., peak morning rounds vs. overnight shifts), ensuring performance without over-provisioning.

4. Edge-Optimized Frontend (Next.js)

Your Next.js 14 frontend requires more than static hosting due to its server-side logic (SSR/ISR).

  • Global Distribution: Using Vercel or Azure SWA ensures that the initial EMR dashboard load is generated at the data center closest to the clinician, minimizing latency.
  • PWA & Offline Capability: Managed hosting platforms optimize the delivery of Service Workers, crucial for Halkyone’s offline-first clinical documentation strategy.

5. Secure Storage via SAS

Storing patient PDFs or images in a public folder is a security violation.

  • SAS (Shared Access Signatures): The API generates short-lived, encrypted URLs that expire in minutes. The frontend uses these to display records, ensuring that clinical data direct links are never permanently exposed.

🛡️ Hardening Implementation Plan

Below are step-by-step variations for implementing the most critical infrastructure requirements.

Part 1: SignalR Scaling (Live Telemetry Backplane)

Variation A: Azure SignalR Service (Managed)

  1. Provision: Create an Azure SignalR Service instance in the same region as your API.
  2. Install: Run dotnet add package Microsoft.Azure.SignalR in the Api project.
  3. Configure: Update Program.cs: 
    builder.Services.AddSignalR().AddAzureSignalR(options => {
    options.ConnectionString = builder.Configuration["Azure:SignalR:ConnectionString"];
});
  4. Security: Use Microsoft Entra ID managed identities to avoid storing raw keys.

Variation B: Redis Backplane (Self-Managed)

  1. Setup: Deploy a Redis instance (or use Azure Cache for Redis).
  2. Install: Run dotnet add package Microsoft.AspNetCore.SignalR.StackExchangeRedis.
  3. Configure: Update Program.cs: 
    builder.Services.AddSignalR().AddStackExchangeRedis("your-redis-connection-string");

Part 2: Zero-Downtime Database Migrations

Variation A: The "Expand-Contract" Pattern

  1. Expand: Run a migration that adds new columns/tables (no breaking changes).
  2. Dual Write: Update ApplicationDbContext to write data to both old and new columns.
  3. Backfill: Execute a background task to sync existing data to the new schema.
  4. Contract: Once verified, deploy a final migration to remove the deprecated columns.

Variation B: Blue-Green Tenant Switching

  1. Parallel Provisioning: Spin up a "Green" DB instance with the new schema.
  2. Logical Sync: Use Azure Data Factory to sync data from the production database to the Green database.
  3. Toggle Switch: Update the TenantResolver middleware to point specific tenants to the Green database for verification before a full cutover.

📈 Go-To-Market Infrastructure

"Halkyone Clinical OS is engineered for rapid, secure cloud deployment. The .NET 9 API and Next.js frontend are decoupled and containerized. The target production environment utilizes Microsoft Azure to ensure enterprise-grade security. By leveraging Azure SQL for encrypted, multi-tenant data isolation and Azure SignalR Service for high-throughput live clinical telemetry, the platform is designed to be highly available, scalable, and fully compliant with healthcare data privacy regulations from day one."

🛠️ Deployment Checklist

  • Configure NEXT_PUBLIC_API_URL for the frontend.
  • Provision Azure SignalR Service and update connection strings.
  • Set up Azure Key Vault for secret management (API Keys, SQL Credentials).
  • Configure Application Insights for real-time clinical monitoring and logging.