System
Architecture
Production path: Browser → Cloudflare (DNS/TLS/WAF) → host Nginx → PM2 on localhost (hmis-web :3000, hmis-api :4000). Each hospital gets an isolated deployment with its own database, not multi-tenant SaaS.
Platform core
Edge + Origin + Clinical Data Mesh
Production Delivery Mesh
Documented in docs/info/SECURITY-HARDENING.md and infra/nginx/. PM2 ports bind localhost; only Nginx listens on 80/443.
Cloudflare at the Edge
Zone proxy
Public HTTPS terminates at Cloudflare before origin Nginx. Incident response may block ASNs at the edge (docs/info/policies/INCIDENT-RESPONSE-POLICY.md).
Turnstile
Public write routes use Cloudflare Turnstile (TURNSTILE_SECRET, NEXT_PUBLIC_TURNSTILE_SITE_KEY). Login stays rate-limited only.
Real client IP
Install infra/nginx/cloudflare-real-ip.conf so Nginx restores CF-Connecting-IP. Keep TRUST_PROXY=1 on the API.
API Shield (optional)
Upload api/openapi/openapi.cloudflare.json via npm run export:openapi-cloudflare for high-risk /api/v1 schema validation.
Cloudflare Tunnel, R2, and Workers are not documented as required HMIS production components unless your hospital adds them outside this repo.
Stack
Governance
Micro-monolith: unified Prisma schema across 170+ models. Docker Compose runs data + observability on localhost; application processes run under PM2 on the host (infra/README.md).
Technical Architecture
| Field | Type | Institutional Role |
|---|---|---|
| Frontend | Next.js (TypeScript) | App Router / RSC, PM2 hmis-web :3000. |
| Backend | Express / Node ≥20 | PM2 hmis-api :4000, JWT, RBAC, Socket.IO. |
| Edge | Cloudflare + Nginx | Zone proxy, Turnstile, real_ip → TRUST_PROXY. |
| Database | PostgreSQL 16 | Clinical OLTP, Docker Compose on localhost. |
| ORM | Prisma | Type-safe schema; migrate deploy on release. |
| Identity | OIDC (optional) | GET /auth/oidc/*, Settings or SSO_OIDC_* env. |
Note: Sensitive fields use AES-256 field-level encryption where applicable.
Governance & Power
settings:adminaudit:exportData Sovereignty
PII and clinical data use AES-256-GCM field encryption where configured. Audit ledgers are append-only with chain hashing. Media and PDFs live in private S3-compatible buckets, not on the web origin.
Deploy & Observability
Deploy gate
npm run test:deploy then bash scripts/deploy-pm2.sh, api, worker, scheduler, web.
Data plane
docker compose up -d, Postgres, Redis, MongoDB, Prometheus, Loki, Grafana (localhost).
Telemetry
Optional Sentry (DSN); Prometheus/Grafana dashboards under infra/grafana/.
Redis: rate limits, BullMQ jobs, query cache, Socket.IO adapter when API is clustered.
Multi-campus: clinical Branch + Working-in, org-wide exceptions: staff chat, patient chart by id, public pages.
Reference docs:
- docs/info/SECURITY-HARDENING.md
- docs/info/DR-PLAYBOOK.md
- docs/info/PERFORMANCE.md
- docs/info/OBSERVABILITY.md
- docs/info/SSO-OPERATIONS.md
- infra/README.md