Implemented platform — enterprise & system architecture (as-built)

Generated: 2026-04-03
Updated: 2026-04-11 — capability map §1.1 includes health-population; see also platform/NATIONAL_EHEALTH_VISION.md.
Method: Repository discovery (apps/, packages/, infra/, specs/architecture/baseline/) per ARCHITECTURE_DOCUMENTATION_PROMPT.md.
Normative baseline (rules): baseline/ARCHITECTURE_BASELINE.md.

---

Evidence and limits

Topic	Status
Service list & Dockerfiles	apps/services/*, infra/docker-compose.yml
HTTP edge routing	infra/kong/kong.yml
Multi-DB on one Postgres	infra/docker-compose.yml + infra/db-init/multi
ehr-web default API host in sample env	apps/ehr-web/.env.example points to mock NEXT_PUBLIC_API_URL — production uses Kong + real services per baseline
Per-route “stub vs complete”	Not exhaustively audited here; use ../_generation/SERVICE_BASELINE_AUDIT_TRACKER.md and module SPEC.md

---

Deliverable 1 — Enterprise architecture (as implemented)

1.1 Business capabilities → services (capability map)

Abbreviated mapping; each row’s service owns its DB and APIs per baseline. Rationale is business-facing.

Business capability	Service(s) (folder under apps/services/)	One-line business rationale
Identity & sign-in	iam	Issue and validate identities used across all apps.
Tenancy & org setup	tenant, hierarchy, licensing	Isolate customers, scope work to org units, enable/disable products.
Fine-grained access	access-policy	Enforce who may see or change what (ABAC/RBAC evaluation).
Audit & compliance evidence	audit	Record sensitive access and changes for accountability.
UI/config resolution	config-resolver	Deliver tenant-appropriate configuration to clients.
Terminology & codes	terminology	Keep clinical and billing language consistent and searchable.
Platform administration	platform-admin	Operate the platform (users, settings) outside day-to-day clinical care.
Patient intake & demographics	registration	Register patients and maintain master demographic records.
Patient chart index	patient-chart-service	Anchor the longitudinal record for care delivery.
Scheduling & capacity	scheduling	Book and manage visits and time-based resources.
Provider directory	provider-directory	Know who delivers care and how to find them.
Facilities & locations	facility	Model where care happens for routing and reporting.
Clinical documentation	clinical-notes	Capture narrative care documentation.
Document management (PDF templates, chart documents)	document-management	Template-backed PDF generation, DocumentReference / Binary storage, imports and print/view audit — see ../modules/document-management/SPEC.md.
Orders (CPOE)	orders	Request tests, imaging, referrals, and other orders.
Results	results	Store and surface diagnostic and other results.
Medications	medication	Manage medication-related clinical data.
Pharmacy (dispensing domain)	pharmacy	Queue, inventory, controlled-substance rules, billing hooks, pharmacist portal APIs (licensed module PHARM-RX). Ghasi Pharmacy fulfills interoperable prescriptions by reading/writing MedicationRequest / MedicationDispense through the e-prescribing gateway (not by duplicating that boundary in pharmacy).
Ghasi e-prescribing gateway (national medication interop)	e-prescribing-gateway	Prescribe→dispense spine for Ghasi EHR ↔ Ghasi Pharmacy: FHIR façade, subscriptions, idempotency, gateway persistence, multi-tenant routing; Kong /v1/ghasi-e-prescribing-gateway — see GHASI_EPRESCRIBING_GATEWAY.md.
Allergies	allergies	Record and surface allergy/intolerance information.
Problems / diagnoses	problem-list	Maintain active and historical problem lists.
Vitals	vitals	Capture and retrieve vital signs.
Care plans	care-plans-service	Document planned care across time.
Immunizations	immunizations	Track immunization history and forecasts.
Population health (analytics)	health-population	Cohort definitions, chronic registries, screening/immunization coverage aggregates, risk stratification, outreach lists, quality metrics — see ../modules/health-population/SPEC.md.
Patient engagement (portal API)	patient-portal-api	Expose patient-facing workflows (appointments, record slices, etc.).
Digital Communication	digital-communication	Secure messaging, outbound notifications, and virtual visits (telehealth); supersedes separate messaging and virtual-care deployables — see ADR-0047.
Laboratory (LIS)	laboratory-lis	Support lab workflows and connectivity.
Radiology / PACS	radiology-pacs	Support imaging workflows and storage integration.
Interop (HL7 v2)	hl7v2-interop	Ingest/exchange legacy HL7 messages into the platform.
Canonical FHIR HTTP	fhir-gateway	Expose FHIR R4 to partners; routes resources to owning domain services (not the same as the e-prescribing gateway).
Billing	billing	Support revenue cycle operations tied to encounters.
Insurance	insurance	Manage payer and coverage information.
Claims	claims	Prepare and track claims submission.
AI-assisted workflows (licensed)	ai-orchestrator	Centralize model calls with policy and audit hooks.
Seeds & demos	seed-runner	Populate data for development/demos (not a runtime edge service).

1.2 Identity, trust boundaries, tenancy

• AuthN: Baseline specifies Keycloak OIDC and JWT validation at Kong and each NestJS service (infra/kong/kong.yml auth notes; ARCHITECTURE_BASELINE.md §7).
• AuthZ: Access Policy internal API — e.g. ehr-web server route calls ACCESS_POLICY_INTERNAL_URL → /internal/access/context when configured (apps/ehr-web/src/app/api/access/resolved-profile/route.ts). If unset, broad demo permissions are returned (same file) — dev-only behavior.
• Tenancy: Baseline requires tenant_id on requests/entities (ARCHITECTURE_BASELINE.md §2). JWT claims include tenant (resolved-profile decodes tenant_id / tenantId).
• Trust zones: Browser → Next.js BFF (session) → Kong → microservices; /internal/* routes restricted in Kong (kong.yml ip-restriction for private ranges).

Evidence: infra/kong/kong.yml, specs/architecture/baseline/ARCHITECTURE_BASELINE.md, apps/ehr-web/src/app/api/access/resolved-profile/route.ts.

1.3 Regulatory / safety (repo-grounded only)

• Audit service exists (audit/) per baseline audit expectations.
• ABAC delegated to access-policy — not embedded in UI (ARCHITECTURE_BASELINE.md §7).
• No claim of HIPAA/ISO certification in this doc; detailed compliance is out of scope unless asserted in explicit product/compliance artifacts.

1.4 Environments

• Local infra: scripts/start-infra.ps1 + infra/docker-compose.yml — Postgres (multi logical DBs), Redis, NATS, Keycloak, Kong, MinIO, Elasticsearch stack (start-infra.ps1 lists services).
• Build-time env: turbo.json passes KONG_URL, KEYCLOAK_*, ACCESS_POLICY_INTERNAL_URL, etc., for apps that need them.
• CI: Root package.json includes test:kong-contracts → infra/kong/kong.declarative.contract.test.mjs.

1.5 External integration patterns (in repo)

• FHIR R4: fhir-gateway — baseline §3, §6.2.
• HL7 v2: hl7v2-interop.
• Kong as single browser-facing HTTP edge for production clients — baseline §6.4.

---

Deliverable 2 — Combined system design (whole platform)

2.1 Logical architecture (monorepo)

• Apps: apps/ehr-web, ehr-desktop, patient-portal, ehr-patient-mobile, lab-portal, pharmacy-portal — six consumer UIs.
• Services: apps/services/* — Nest (typical) microservices, each with own DB user/name on shared Postgres (docker-compose.yml env block).
• Shared libraries: packages/@ghasi/* — e.g. auth-client, access-client-browser, nats-client, nestjs-common, event-schemas, shared-types.
• Orchestration: turbo monorepo (package.json scripts, turbo.json).

Dependency direction (intended): UI → shared clients → Kong URLs → services; services → other services via REST /internal/* or NATS JetStream per baseline §5.

2.2 Runtime architecture

Evidence: infra/kong/kong.yml, infra/docker-compose.yml.

2.3 Data architecture

• One PostgreSQL instance, one logical database per service (credentials in docker-compose.yml — pattern: *_DB_NAME, *_DB_USER).
• No shared DBs across services (baseline §1, §8).
• Events: NATS JetStream + CloudEvents envelope (ARCHITECTURE_BASELINE.md §5).
• Object storage: MinIO in compose (for artifacts where implemented).

2.4 Cross-cutting

Concern	Where visible
Correlation / tracing	Baseline §11; Kong correlation-id note in kong.yml
Rate limiting	Kong plugins on routes (kong.yml)
Licensing	licensing + MODULE_NOT_ACTIVE pattern (baseline §9)
Feature flags / config	config-resolver; client ui-config-client-browser in portal apps

2.5 End-to-end paths

A) Clinician path (ehr-web → services)

1. User signs in via OIDC (Keycloak) — session in Next.js (next-auth / authOptions pattern in repo).
2. Browser calls Next.js API routes or server components; server may call access-policy for permissions (resolved-profile).
3. Clinical data requests go to Kong base URL (when configured to real backend) → e.g. patient-chart-service, orders, etc. (per kong.yml service routes).

Note: Default apps/ehr-web/.env.example still uses mock NEXT_PUBLIC_API_URL; align env with Kong for real integration.

B) Patient path (portal or mobile → Kong → portal/scheduling/results)

1. OIDC token for patient realm/client.
2. Kong /v1/portal → patient-portal-api (kong.yml patient-portal-root).
3. Additional /v1/* routes hit scheduling, provider directory, results, etc. — see specs/architecture/platform/mobile-app/BACKEND_AND_SERVICE_MAP.md for known patient/staff guard gaps.

C) Failure / resilience (only if implemented)

• Baseline describes retries, idempotent consumers, DLQ for NATS — verify per service code for actual handlers.
• Kong rate-limiting plugins visible in kong.yml.

---

Deliverable 3 — Per service (business case + technical summary)

Below: for each deployable service folder, business subsections (1–6) in compact form, then technical bullets.
Diagrams (per service): See PER_SERVICE_DIAGRAMS.md — one container-style and one sequence diagram per apps/services/* entry, with Kong routes and ports taken from ../../infra/kong/kong.yml. Platform-level views remain in §2 and §4 below.

---

Platform & governance

iam (iam)

1. Business purpose: Establish and prove user identities for every workflow.
2. Stakeholders: Primary: IT, security, all users. Secondary: compliance.
3. Value: Consistent login and token issuance; supports zero-trust validation downstream.
4. Scope: Identity lifecycle and auth APIs; not clinical content.
5. Depends on: Keycloak integration patterns; other services depend on IAM-issued tokens.
6. Risks: Misconfiguration breaks all apps.

Technical: Kong /api/iam, /internal/iam (kong.yml); Dockerfile present.

tenant (tenant)

1. Business purpose: Separate customer organizations and their configuration.
2. Stakeholders: Primary: tenant admins, IT. Secondary: finance.
3. Value: Data and licensing isolation between customers.
4. Scope: Tenant CRUD and related APIs.
5. Depends on: IAM; consumed by almost all domains.
6. Risks: Wrong tenant context → wrong data exposure (mitigated by ABAC + guards).

Technical: /api/tenants, /internal/tenants; own DB.

hierarchy (hierarchy)

1. Business purpose: Model org structure (sites, departments) for scoping work and licenses.
2. Stakeholders: Primary: operations, clinical leadership. Secondary: finance.
3. Value: Correct roll-ups and access at the right org level.
4. Scope: Hierarchy nodes; not clinical documents.
5. Depends on: Tenant; licensing uses nodes per baseline.
6. Risks: Complex DAG misconfiguration affects access and reporting.

Technical: /api/hierarchy, /internal/hierarchy.

licensing

1. Business purpose: Turn product modules on or off per contract.
2. Stakeholders: Primary: commercial, IT. Secondary: clinical (feature availability).
3. Value: Pay for what you use; prevent use of unpaid modules (MODULE_NOT_ACTIVE).
4. Scope: License evaluation; not clinical decision support.
5. Depends on: Hierarchy nodes; services call internal licensing APIs.
6. Risks: Mis-seeded licenses hide features or block legitimate work.

Technical: /api/licenses, /internal/licenses.

access-policy

1. Business purpose: Answer “may this user perform this action on this record?” for ABAC.
2. Stakeholders: Primary: security, compliance. Secondary: product/engineering.
3. Value: Central policy vs scattered role checks in each service.
4. Scope: Policy evaluation; not storage of clinical facts.
5. Depends on: IAM claims, tenant, hierarchy context.
6. Risks: Policy gaps → over- or under-access until policies mature.

Technical: Internal /internal/access/*; ehr-web uses ACCESS_POLICY_INTERNAL_URL when set.

audit

1. Business purpose: Retain evidence of who did what to sensitive data.
2. Stakeholders: Primary: compliance, security. Secondary: operations.
3. Value: Forensics and accountability.
4. Scope: Audit events; not primary clinical chart storage.
5. Depends on: Caller identity from tokens; services emit audit-worthy events.
6. Risks: Incomplete instrumentation → weak audit trail.

Technical: Dedicated audit DB in compose; internal routes per Kong.

terminology

1. Business purpose: Use standard codes (LOINC, SNOMED, etc.) so data is comparable and billable.
2. Stakeholders: Primary: clinicians, lab, billing. Secondary: data/analytics.
3. Value: Fewer mapping errors; better reporting.
4. Scope: Terminology search/maintenance; not orders execution itself.
5. Depends on: Tenant; consumed by clinical and billing modules.
6. Risks: Stale terminology → wrong codes on records.

Technical: Own DB; exposed per Kong clinical/platform sections.

platform-admin

1. Business purpose: Operate users, roles, and cross-cutting admin tasks.
2. Stakeholders: Primary: IT admins. Secondary: security.
3. Value: Day-2 operations without database access.
4. Scope: Admin APIs; not patient care workflows.
5. Depends on: IAM, tenant, hierarchy.
6. Risks: Over-privileged admins — baseline expects guardrails.

Technical: Dockerfile present; routes in kong.yml (admin section).

config-resolver

1. Business purpose: Deliver correct UI and feature configuration per tenant/node.
2. Stakeholders: Primary: product, IT. Secondary: end users (correct UX).
3. Value: One deployment, many tenant experiences.
4. Scope: Config resolution; not clinical authoring.
5. Depends on: Tenant/hierarchy; clients use @ghasi/ui-config-client-browser.
6. Risks: Wrong config → wrong modules exposed.

Technical: Own DB; internal URL pattern in turbo env list.

---

Registration & chart

registration

1. Business purpose: Create and maintain legal/clinical identity of patients entering the system.
2. Stakeholders: Primary: front desk, registration. Secondary: billing.
3. Value: Clean master patient index; fewer duplicates.
4. Scope: Demographics and registration workflows.
5. Depends on: Tenant; feeds chart and scheduling.
6. Risks: Duplicate patients if matching not enforced in product.

Technical: Registration DB; Kong /v1/... registration routes (see kong.yml clinical sections).

patient-chart-service

1. Business purpose: Provide the longitudinal “chart” context for care teams.
2. Stakeholders: Primary: clinicians, nurses. Secondary: quality.
3. Value: One place to see patient context for decisions.
4. Scope: Chart aggregates and pointers; module facts may live in domain services.
5. Depends on: Registration, licensing, access-policy.
6. Risks: Overlap with module services if boundaries blur.

Technical: ghasi-patient-chart container in compose; module code ehr.chart in baseline.

---

Clinical modules

clinical-notes, orders, results, medication, allergies, problem-list, vitals, care-plans-service, immunizations

Shared pattern:

1. Business purpose: Capture and retrieve a specific clinical domain for safe care and continuity.
2. Stakeholders: Primary: clinical staff. Secondary: patients (via portal when exposed), billing (downstream).
3. Value: Structured data for decisions, orders, and results lifecycle.
4. Scope: Domain-specific resources; cross-domain orchestration via APIs/events.
5. Depends on: Patient context, access-policy, often terminology; orders/results may chain.
6. Risks: Partial implementation in any one domain forces workarounds in others.

Technical: Each has own DB in docker-compose.yml; REST under /v1/... per Kong clinical.yaml / kong.yml; NATS events per orders module specs (specs/modules/orders-cpoe/NATS_AND_CONSUMERS.md).

---

Engagement & diagnostics

patient-portal-api

1. Business purpose: Let patients interact with their care (appointments, health record slices) without staff intermediaries.
2. Stakeholders: Primary: patients. Secondary: care teams (fewer phone calls).
3. Value: Access and convenience; reduced administrative load.
4. Scope: Portal BFF/APIs under /v1/portal; not full clinician chart.
5. Depends on: IAM patient tokens, scheduling, provider directory, results release policies.
6. Risks: Authorization gaps for patient vs staff documented in BACKEND_AND_SERVICE_MAP.md and patient-portal backlog specs.

Technical: Kong route /v1/portal → patient-portal-api:3030.

digital-communication

1. Business purpose: All non–in-person mediated communication — secure async messaging, outbound notifications (push/SMS/email), and virtual visits (synchronous telehealth session lifecycle and video stack).
2. Stakeholders: Primary: patients and staff. Secondary: compliance, operations.
3. Value: Single channel for retention/UI; coordinated virtual care without a second microservice.
4. Scope: Threads, notifications, virtual sessions; not canonical chart storage (clinical-notes / FHIR owners).
5. Depends on: Identity, access-policy, patient linkage, scheduling (VR appointments), optional ai-orchestrator (STT).
6. Risks: PHI in messages and session metadata — audit, access, PHI-minimized notifications.

Technical: Own DB (unified messaging + virtual session tables); Kong routes /v1/digital-communication with legacy aliases — specs/modules/digital-communication/SPEC.md.

scheduling, provider-directory, facility

1. Business purpose: Find care, book time, and know where and with whom care happens.
2. Stakeholders: Primary: patients, schedulers, providers. Secondary: operations.
3. Value: Full schedules and fewer no-shows (when reminders exist).
4. Scope: Scheduling and directory; not billing adjudication.
5. Depends on: Registration (patient), hierarchy (locations), licensing.
6. Risks: Patient booking vs staff-only APIs — see mobile backend map.

Technical: Each service + DB; /v1/schedules, /v1/practitioners, etc. per Kong.

laboratory-lis, radiology-pacs

1. Business purpose: Run diagnostic workflows and connect to lab/imaging ecosystems.
2. Stakeholders: Primary: lab/radiology staff. Secondary: ordering clinicians.
3. Value: Turnaround and traceability from order to result.
4. Scope: Diagnostic departments; clinical interpretation may stay in chart/notes.
5. Depends on: Orders/results; may integrate instruments/PACS via adapters.
6. Risks: Interface downtime blocks result posting — needs monitoring per baseline observability.

Technical: Dedicated DBs in compose; service containers.

---

Interop & canonical APIs

fhir-gateway

1. Business purpose: Expose standard FHIR R4 so external systems can integrate with Ghasi EHR clinical domains using one contract; it proxies to owning services and does not add Ghasi-internal medication workflow features beyond that routing.
2. Stakeholders: Primary: integration engineers, HIE partners. Secondary: product.
3. Value: Replace one-off interfaces with a standard contract.
4. Scope: FHIR HTTP API; mapping from internal models; MedicationRequest/MedicationDispense on /fhir/R4 route to pharmacy per resource ownership map.
5. Depends on: Underlying domain services and FHIR-first rules in baseline.
6. Risks: Incomplete resource coverage limits partner onboarding.

Technical: /fhir/R4/... via Kong; container ghasi-fhir-gateway. Not the Ghasi e-prescribing gateway — national prescribe–dispense interop uses e-prescribing-gateway (/v1/ghasi-e-prescribing-gateway).

e-prescribing-gateway (Ghasi e-prescribing gateway)

1. Business purpose: National / enterprise medication interoperability between prescriber-side systems and pharmacies — Ghasi EHR and Ghasi Pharmacy first; additional EMRs/EHRs and pharmacies later.
2. Stakeholders: Primary: platform interop, pharmacy and prescribing product teams, national integrators. Secondary: compliance.
3. Value: Single gateway contract for prescription routing, notifications, and audit at the interop boundary.
4. Scope: FHIR façade under /v1/ghasi-e-prescribing-gateway, subscriptions, idempotency, gateway persistence per ADR-0044; not a replacement for terminology, orders, or generic /fhir/R4. Ghasi Pharmacy uses this service as the fulfillment interop layer for prescribed medications (alongside pharmacy for queue/inventory/product logic).
5. Depends on: Kong, IAM, audit, NATS, Postgres; clinical systems consume/produce FHIR per module specs.
6. Risks: Confusion with fhir-gateway — mitigated by GHASI_EPRESCRIBING_GATEWAY.md §2.1.

Technical: Kong /v1/ghasi-e-prescribing-gateway; see apps/services/e-prescribing-gateway, specs/modules/ghasi-e-prescribing-gateway/.

hl7v2-interop

1. Business purpose: Connect to legacy HL7 feeds common in hospitals and labs.
2. Stakeholders: Primary: integration, lab, ADT interfaces. Secondary: clinical ops.
3. Value: Ingest/exchange events without rewriting all external systems.
4. Scope: HL7 v2 adapters; canonical model still FHIR per baseline.
5. Depends on: Orders/results/patient identity correlation.
6. Risks: Message duplication — baseline requires idempotency (ARCHITECTURE_BASELINE.md §6).

Technical: Own DB; Dockerfile present.

ai-orchestrator

1. Business purpose: Offer AI features without letting clients call models directly.
2. Stakeholders: Primary: product, clinical innovators. Secondary: compliance.
3. Value: Draft assistance, documentation help — when licensed and audited.
4. Scope: Orchestration only; not a source of truth for clinical facts.
5. Depends on: Licensing, audit, access-policy per baseline AI section.
6. Risks: Trusting draft content without clinician finalization.

Technical: ghasi-ai-orchestrator in compose; must sit behind Kong per baseline §14.

---

Revenue cycle

billing, insurance, claims

1. Business purpose: Capture charges, manage coverage, and pursue payment for services rendered.
2. Stakeholders: Primary: billing office, revenue cycle. Secondary: patients (statements).
3. Value: Cash flow and fewer denials when data is complete.
4. Scope: Financial; not primary clinical decision-making.
5. Depends on: Encounters/orders from clinical domains; payer interfaces.
6. Risks: Coding/terminology misalignment → claim rejection.

Technical: Separate DBs each; Kong /v1/... billing routes in kong.yml.

---

Tooling

seed-runner

1. Business purpose: Accelerate demos and developer onboarding with realistic data.
2. Stakeholders: Primary: engineering, sales engineering. Secondary: QA.
3. Value: Repeatable environments.
4. Scope: Not a production patient-facing service.
5. Depends on: Migrations and service availability.
6. Risks: Must never point production-like PHI at non-prod without policy.

Technical: docker-compose.yml notes no container for seed-runner; run via pnpm scripts (package.json db:seed*).

---

Consumer app shells (brief)

ehr-web

• Business: Primary clinician and staff web EHR.
• Tech: Next.js 16, MUI, next-auth, axios NEXT_PUBLIC_API_URL.
• Auth: OIDC/Keycloak via NextAuth (authOptions); optional mock permissions without access-policy URL.
• Differs: Richest Berry/MUI surface; BFF API routes for access resolution.

ehr-desktop

• Business: Same personas as web with offline-first and desktop deployment.
• Tech: Electron + Vite, better-sqlite3, React Router.
• Auth: Aligns with Kong + OIDC per desktop specs (specs/architecture/platform/desktop-electron/).
• Differs: Local SQLite queue for sync — see offline spec.

patient-portal

• Business: Patient self-service web (dashboards, widgets).
• Tech: Next.js on port 3100, @ghasi/patient-portal-client, next-auth.
• Auth: OIDC + session; uses shared @ghasi/auth-client.
• Differs: Portal-specific UX packages and /v1/portal APIs.

ehr-patient-mobile

• Business: Native patient experience (iOS/Android).
• Tech: Expo, expo-router, Mapbox/location plugins (app.json).
• Auth/API: Kong patient routes per BACKEND_AND_SERVICE_MAP.md (EXPO_PUBLIC_KONG_PUBLIC_BASE_URL in turbo).
• Differs: Mobile navigation, push/deep links per mobile-app specs.

lab-portal

• Business: Lab staff workflows (incoming work, connectivity context).
• Tech: Next.js + design-system + auth/access clients (no next-auth in package.json — verify auth wrapper in app).
• Differs: Persona tuned to laboratory operations; routes to LIS/results services via Kong.

pharmacy-portal

• Business: Pharmacy operations and fulfillment (queue, verify, dispense, label print).
• Tech: Same stack pattern as lab-portal.
• Differs: For Ghasi EHR ↔ Ghasi Pharmacy workflows, fulfillment is aligned with the Ghasi e-prescribing gateway (/v1/ghasi-e-prescribing-gateway) for FHIR medication interop, while domain data (inventory, charges, local policy) still flows through pharmacy and related platform APIs — see GHASI_EPRESCRIBING_GATEWAY.md and pharmacy SPEC.

---

Deliverable 4 — Whole platform: flows, journeys, diagrams

4.1 Platform context (high level)

(For formal C4 views, export from Structurizr or your EA tool using this section as input.)

4.2 Data flow (simplified)

Evidence: Baseline event rules; HL7 service presence; exact subjects per module NATS docs.

4.3 User journeys (capability level)

Clinician (ehr-web / ehr-desktop)

1. Authenticate (OIDC).
2. Resolve permissions (access-policy when configured).
3. Open patient chart → calls chart + domain services via Kong.
4. Place orders → orders → downstream lab/LIS via events/integration.
5. Review results → results.

Patient (patient-portal / ehr-patient-mobile)

1. Authenticate (patient client).
2. Home/summary via patient-portal-api /v1/portal.
3. Book/cancel — verify patient-eligible APIs per BACKEND_GAPS_AND_ROADMAP.md.
4. View released results — align with results policy and JWT patient binding.

Lab user (lab-portal)

1. Staff authentication.
2. Work queues and interfaces via LIS + results + orders context (routes per Kong).
3. Exception handling when HL7 or instrument feeds fail — operational monitoring.

Pharmacy user (pharmacy-portal)

1. Staff authentication.
2. Prescription intake and fulfillment for the Ghasi product stack: new/updated MedicationRequest instances and MedicationDispense writes go through the Ghasi e-prescribing gateway so prescribers and pharmacies share one national interop contract (ETags, subscriptions, correlation).
3. pharmacy (and portal BFF) still owns dispensing domain behavior: queue, stock decrement, controlled-substance checks, and billing events — orchestrated with the gateway, not in place of it.
4. Coordination with billing/coverage as implemented.

---

Executive summary (one page)

The Ghasi EHR repository implements a Turbo monorepo with six consumer applications (clinician web, Electron desktop, patient web portal, Expo patient mobile, lab portal, pharmacy portal) and ~32 service folders under apps/services, each aligned to a bounded context with its own database on a shared PostgreSQL instance in local Docker. Kong is the HTTP API gateway; Keycloak provides OIDC/JWT; NATS JetStream carries domain events; Redis and MinIO support caching and object storage patterns. The FHIR gateway exposes FHIR R4 for partner integration with clinical domain services; e-prescribing-gateway implements the Ghasi e-prescribing gateway for national medication interop (/v1/ghasi-e-prescribing-gateway), including Ghasi Pharmacy fulfillment of prescriptions from Ghasi EHR prescribers alongside pharmacy domain logic. HL7 v2 interop handles legacy feeds. Access policy centralizes ABAC evaluation (wired in ehr-web when ACCESS_POLICY_INTERNAL_URL is set). Licensing gates modules per hierarchy node.

Business value: The platform separates tenant isolation, clinical domains, patient engagement, diagnostics, and revenue cycle into services so teams can evolve contracts independently while presenting a unified experience through the portals and EHR clients.

Caveats: Not every route is patient-ready or feature-complete — patient booking and staff-guard issues are documented for mobile/portal. ehr-web sample env still references a mock API host; real runs must target Kong and service URLs. Treat this document as an as-discovered map; pair with module SPEC.md and the service baseline audit for completeness.

---

Glossary

Term	Meaning in this repo
Kong	Declarative gateway (infra/kong/kong.yml) fronting services.
Keycloak	OIDC IdP for JWTs validated at gateway and services.
Bounded context	One deployable service owning schema + APIs + events (ARCHITECTURE_BASELINE.md).
Tenant	Organization slice; tenant_id on entities and tokens.
Hierarchy node	Org unit in DAG for scoping and licensing.
Portal	Patient-facing APIs under /v1/portal via patient-portal-api.
FHIR gateway	fhir-gateway exposing /fhir/R4 to domain owners.
Ghasi e-prescribing gateway	e-prescribing-gateway — national medication interop (Ghasi EHR prescribe → Ghasi Pharmacy fulfill); Kong /v1/ghasi-e-prescribing-gateway (GHASI_EPRESCRIBING_GATEWAY.md).
seed-runner	Tooling to seed databases, not an edge microservice.

---

Gaps to verify next

1. Production URL matrix for each app (exact Kong public base URLs per environment).
2. Per-service OpenAPI completeness vs implementation.
3. Patient vs staff authorization on every /v1/* route used by portal/mobile.
4. ehr-web migration from mock NEXT_PUBLIC_API_URL to Kong-backed client in all non-demo envs.
5. Observability wiring (OTel) per service — baseline prescribes; confirm exporters in each main.ts.