Platform Technology Stack — Ghasi EHR

Scope: Canonical technology choices enforced across the entire platform.
Authority: Normative. All services MUST use these technologies unless an exception is explicitly documented and approved.

---

1. Core Stack

Layer	Technology	Version / Notes
Language	TypeScript	strict: true; shared types in packages/@ghasi/shared-types
Backend	NestJS	One process per microservice
Frontend	Next.js 16	App Router; clinician shell + patient portal route group
UI Framework	MUI v6 + Emotion	RTL-aware theme; design tokens in packages/@ghasi/ui-tokens
Database	PostgreSQL 16	Per-service isolated database; migrations via TypeORM
ORM	TypeORM	Migration-based only; synchronize: false in production
Cache	Redis 7	Entitlement cache, FHIR conformance, search typeaheads
Event Bus	NATS JetStream	Durable streams; CloudEvents envelope; DLQ mandatory
Auth	Keycloak (OIDC)	JWT via JWKS; separate realm/client for patient portal
API Gateway	Kong (DB-less)	Routes /v1/* (REST) and /fhir/R4/* (FHIR)
Object Storage	MinIO	Attachments, documents, scanned files
Observability	OpenTelemetry	Traces + metrics + structured logs
Testing	Jest + Supertest + Playwright	Unit/integration/contract/E2E

2. Monorepo Structure

ghasi-ehr/
  apps/
    web/                          # Next.js 16 frontend
    services/
      iam/                # MVP0
      access-policy/      # MVP0
      tenant/             # MVP0
      hierarchy/          # MVP0
      licensing/          # MVP0
      audit/              # MVP0
      terminology/        # MVP0
      platform-admin/     # MVP0
      registration/       # MVP1
      scheduling/         # MVP1
      provider-directory/ # MVP1
      facility/           # MVP1
      patient-chart-service/      # MVP1
      clinical-notes/     # MVP1
      orders/             # MVP1
      results/            # MVP1
      medication/         # MVP1
      allergies/          # MVP1
      vitals/             # MVP1
      problem-list/       # MVP1
      fhir-gateway/       # MVP2
      hl7v2-interop/      # MVP2
      immunizations/      # MVP2
      care-plans-service/         # MVP2
      messaging/          # MVP2
      patient-portal-api/     # MVP2
      laboratory-lis/     # MVP2
      radiology-pacs/     # MVP2
      billing/            # MVP2
      insurance/          # MVP2
      claims/             # MVP2
  packages/
    @ghasi/
      shared-types/               # Common DTOs, error codes, types
      event-schemas/              # Zod schemas for CloudEvents
      nats-client/                # NATS helpers, CloudEventsBuilder
      auth-guard/                 # JWT guard, tenant extraction
      access-client/              # ABAC evaluation client
      audit-client/               # Audit event publisher
      test-utils/                 # Test factories, fixtures, mocks
  infra/
    docker-compose.yml
    kong/
    nats/
    keycloak/
  specs/                          # This documentation folder

3. Infrastructure (Local Dev)

Service	Container	Port (default)
PostgreSQL 16	postgres:16-alpine	5432
Redis 7	redis:7-alpine	6379
NATS + JetStream	nats:latest	4222 (client), 8222 (monitor)
Keycloak	keycloak/keycloak:latest	8080
Kong	kong:latest	8000 (proxy), 8001 (admin)
MinIO	minio/minio:latest	9000 (API), 9001 (console)
Each NestJS service	Node.js	3001+ (varies per service)
Next.js web	Node.js	3000

4. Deployment Model

• Containers orchestrated via Docker Compose (local/dev) or Kubernetes (staging/prod).
• Per-service database — each service owns its PostgreSQL database.
• NATS JetStream configured with durable streams per domain area.
• Kong declarative configuration (no DB mode) — routes and plugins in YAML.
• Keycloak exports realm configuration for reproducible setup.

5. CI/CD

• Per-service workflows in monorepo — only affected services rebuilt/tested on change.
• Pipeline stages: lint → unit test (≥80% coverage) → build → integration test → deploy.
• E2E tests (Playwright) run post-deploy in staging.