Skip to main content

Platform interoperability — solution design

Document version: 1.2
Date: 2026-04-04
Status: Normative companion to SPEC.md

Related documents:

1. Architecture Overview​

This layer extends the core platform with:

  • A FHIR Gateway Service providing a consolidated FHIR R4 surface
  • An HL7 v2 Interop Service to ingest/emit v2 messages and map them to canonical FHIR
  • An AI Orchestrator Service (ai-orchestrator) for assistive AI behind Kong (policy, retrieval, provider adapters, audit events)
  • Licensed add-on services (diagnostics, engagement, financial)
┌──────────────────────────────────────────────────────────────────────────────┐
│                               NEXT.JS WEB APP                                │
│  Clinician UI (core + add-ons)                    Patient Portal UI           │
└─────────────────────────────────┬────────────────────────────────────────────┘
                                  │ HTTPS
                         ┌────────▼─────────┐
                         │   API GATEWAY     │  (Kong)
                         │  JWT Validation   │
                         │  Rate Limiting    │
                         │  Route Dispatch   │
                         └──┬───────────┬────┘
                            │           │
                            │           │
              ┌─────────────▼─┐     ┌───▼──────────────────┐
              │  REST APIs     │     │   FHIR R4 Base        │
              │  /v1/*         │     │   /fhir/R4/*          │
              └──────┬─────────┘     └──────────┬───────────┘
                     │                           │
          ┌──────────▼──────────┐     ┌──────────▼──────────┐
          │ Core domain services │     │  fhir-gateway │
          │ (per-domain REST)    │     │  routing + aggregation│
          └──────────┬──────────┘     └──────────┬──────────┘
                     │                           │
                     │                    ┌──────▼────────────────────────────┐
                     │                    │ HL7 v2 / Partner Integrations     │
                     │                    │ hl7v2-interop (MLLP)      │
                     │                    └──────────┬────────────────────────┘
                     │                               │
                     │                               │ External Systems
                     │                               │ ADT / ORM / ORU
                     │                               │ DICOMweb / PACS
                     │                               │ Payer / Clearinghouse
                     │                               │
                     │                    ┌──────────▼──────────────────────────┐
                     │                    │ ai-orchestrator              │
                     │                    │ Kong /v1/ai/* → models (hosted/on-prem)│
                     │                    └──────────┬──────────────────────────┘
                     │                               │ Model vendors (contracted)
                     │
        ┌────────────▼────────────────────────────────────────────────────────┐
        │                     NATS JetStream Event Bus                         │
        │  Subjects: clinical.* | diag.* | engage.* | billing.* | interop.* | ai.* │
        └────────────┬────────────────────────────────────────────────────────┘
                     │
        ┌────────────▼────────────────────────────────────────────────────────┐
        │               Per-service PostgreSQL + shared Redis + MinIO           │
        └──────────────────────────────────────────────────────────────────────┘

2. Design principles​

PrincipleApplication
FHIR-firstAll clinically meaningful facts are exposed via FHIR R4 interactions and mapped per ../platform/FHIR_FIRST_STANDARD.md.
Bounded contextsEach service owns its schema and workflow state; the gateway does not introduce a shared DB.
Multi-tenancy everywheretenantId is enforced on REST, FHIR, events, and integration processing.
Policy-controlled exposureABAC is enforced at FHIR boundary; portal access uses a constrained surface and release rules.
Event-driven decouplingNATS JetStream subjects provide durable distribution and replay for integration workers and projections.
Idempotent integrationsHL7v2 engine stores message control IDs, de-duplicates, and can safely retry processing.
Assistive AIModel access only via ai-orchestrator behind Kong; ABAC-scoped retrieval; human acceptance for record writes per AI_PLATFORM.md.

3. Key Components​

3.1 fhir-gateway​

Responsibilities

  • Provide a single FHIR base endpoint: /fhir/R4/*
  • Publish consolidated CapabilityStatement
  • Route requests to the owning service(s) per SPEC.md §6
  • Apply cross-cutting enforcement:
    • JWT validation (inherited) + resource-level RBAC/ABAC
    • tenant resolution + node scoping
    • consistent OperationOutcome error format

Implementation approach

  • NestJS HTTP service behind Kong
  • Modular router mapping resource types → service adapters
  • For “overlapping” resources (notably Observation and DiagnosticReport), gateway supports:
    • query routing by category/profile when safe
    • fan-out + merge for searches where ownership is split

Persistence

  • No clinical persistence (stateless)
  • Optional short-lived cache of conformance artifacts (Redis)

Folder structure (recommended)

fhir-gateway/
  src/
    app.module.ts
    fhir/
      fhir.controller.ts          # /fhir/R4/* (proxy)
      capability/
        capability.service.ts
      routing/
        resource-router.ts
        ownership-map.ts
      adapters/
        registration.adapter.ts
        scheduling.adapter.ts
        vitals.adapter.ts
        results.adapter.ts
        ...
        validation/
          search-params.validator.ts
          operationoutcome.mapper.ts

3.1.1 Ghasi e-prescribing gateway (e-prescribing-gateway) and medication FHIR routing​

Normative overview: ../GHASI_EPRESCRIBING_GATEWAY.md.

The Ghasi e-prescribing gateway is not the same component as the generic FHIR edge. It implements national / enterprise medication interoperability (prescriber platforms ↔ pharmacies): FHIR R4 façade under Kong /v1/ghasi-e-prescribing-gateway, idempotency, ETags, Subscription delivery with outbox/DLQ, multi-tenant enforcement, and NATS events.

Decision (B1 — dual entrypoint):

TrafficEntryOwning deployable for MedicationRequest / MedicationDispense in this path
General FHIR interop (/fhir/R4)Partner-facing unified FHIR APIpharmacy per ownership-map.ts — domain FHIR projection
Ghasi e-prescribing (national)/v1/ghasi-e-prescribing-gatewaye-prescribing-gateway — interop system of record per ADR-0044

Integrators must use /v1/ghasi-e-prescribing-gateway for gateway-mediated prescribing/dispensing workflows. /fhir/R4 medication resources remain the canonical FHIR route to the pharmacy domain service and do not subsume subscription SLAs or gateway persistence.

3.2 hl7v2-interop​

Responsibilities

  • MLLP listener(s) per tenant/facility connector
  • Parse HL7 v2 messages and persist an immutable message log
  • Map messages to canonical FHIR resources and call the fhir-gateway
  • Emit integration events for observability and downstream workflows

Supported message sets (baseline)

  • ADT: A01/A04/A08/A03/A40
  • ORM: orders outbound and ACK ingestion (where applicable)
  • ORU: results inbound and deduplication

Persistence (minimum tables)

  • interop_connectors
  • hl7_messages (raw + parsed metadata)
  • hl7_processing_attempts
  • hl7_resource_links (message → created/updated FHIR resource ids)

Folder structure (recommended)

hl7v2-interop/
  src/
    app.module.ts
    connectors/
      connectors.controller.ts
      connectors.service.ts
      entities/
    mllp/
      mllp.server.ts
      mllp.session.ts
    parsing/
      hl7.parser.ts
      segments/
    mapping/
      adt.mapper.ts
      orm.mapper.ts
      oru.mapper.ts
    processing/
      inbound.processor.ts
      outbound.publisher.ts
    audit/
    events/

3.3 ai-orchestrator (platform.ai)​

Responsibilities

  • Expose AI HTTP APIs only behind Kong (e.g. /v1/ai/...); no vendor API keys in browser clients (FR-AI-003).
  • Enforce licensing, tenant/org context, and ABAC/minimum necessary before retrieving PHI for prompts (FR-AI-002).
  • Orchestrate model adapters (cloud or on-prem); apply quotas, rate limits, and circuit breaking (FR-NFR-016, FR-NFR-015).
  • Support tool-calling only to allow-listed internal services (e.g. FHIR read/search, terminology) using existing service auth.
  • Emit audit-friendly events (sanitized by default) per AI_PLATFORM.md §6 (FR-AI-006).
  • Record provenance metadata when modules persist accepted outputs (FR-AI-005).

Persistence (minimum)

  • ai_requests (correlation id, tenant_id, actor_id, feature_key, status, timestamps, no raw PHI in default columns)
  • ai_policy_snapshots or config references (effective policy version per tenant/node)
  • Optional encrypted blob store for opt-in prompt/response retention per tenant policy (FR-NFR-018)

Normative detail: AI_PLATFORM.md, FR-AI-001..010 and FR-NFR-015..018 in ../../core/EHR_FUNCTIONAL_REQUIREMENTS.md.

Folder structure (recommended)

ai-orchestrator/
  src/
    app.module.ts
    policy/
    retrieval/          # RAG / FHIR-allowed fetchers
    providers/          # vendor adapters
    tools/              # allow-listed internal HTTP clients
    audit/
    events/

4. Add-on Microservices — Design Summaries​

This section defines implementation-level design anchors for add-on and interop services. Detailed module behavior remains normative in the per-module specs.

4.1 immunizations (Module: clinical.immunizations)​

Canonical FHIR resources: Immunization, optional ImmunizationRecommendation
Primary workflows: record administration/history; query by patient/date; optional forecast generation hooks

Database schema (minimum)

  • immunizations (FHIR-backed JSON + indexed columns)
    • id, tenant_id, patient_id, occurrence_at, status, vaccine_system, vaccine_code, lot_number?, performer_id?, version, created_at, updated_at
  • immunization_forecasts (optional)
    • id, tenant_id, patient_id, generated_at, payload_json

Events

  • clinical.immunizations.events with types: ghasi.immunizations.recorded, ...updated, ...refused, ...forecast.updated

4.2 care-plans-service (Module: clinical.care-plans)​

Canonical FHIR resources: CarePlan, Goal, optional Task
Primary workflows: plan lifecycle; goals; activities/progress; review/closure

Database schema (minimum)

  • care_plans
    • id, tenant_id, patient_id, status, period_start?, period_end?, category_code?, title?, payload_json, version, created_at, updated_at
  • care_plan_goals
    • id, care_plan_id, tenant_id, status, description, target_due?, payload_json, version
  • care_plan_activities (optional if modeling Task locally)
    • id, care_plan_id, tenant_id, status, kind, payload_json, version

Events

  • clinical.careplans.events with types: ghasi.careplans.plan.created, ...updated, ...reviewed, ...activity.completed

4.3 messaging (Module: engage.messaging)​

Canonical FHIR resources: Communication (and optionally CommunicationRequest)
Primary workflows: thread + message + read receipt; patient-linked messages; escalation; PHI-safe notifications

Database schema (minimum)

  • message_threads: id, tenant_id, node_id?, patient_id?, encounter_id?, created_at
  • thread_participants: id, thread_id, participant_type, participant_id
  • messages: id, thread_id, sender_id, sent_at, urgency, body, status
  • message_read_receipts: id, message_id, user_id, read_at
  • message_attachments: id, message_id, file_ref, mime_type, size_bytes, hash, scan_status

Events

Outbound notifications (push / SMS / email)

4.4 patient-portal-api (Module: engage.patient-portal)​

Purpose

  • Patient-facing API surface that:
    • enforces portal-specific policies (release rules, redaction)
    • reads clinical facts via FHIR gateway
    • writes appointment requests to Scheduling
    • writes messaging requests to Messaging

Database schema (minimum)

  • portal_accounts: id, tenant_id, patient_id, idp_subject, status, created_at
  • portal_access_events: id, portal_account_id, event_type, resource_type?, resource_id?, occurred_at
  • demographics_update_requests: id, tenant_id, patient_id, requested_changes_json, status, requested_at, reviewed_at?

Events

  • engage.portal.events with types: ghasi.portal.login, ...record.viewed, ...appointment.requested, ...result.viewed

4.5 laboratory-lis (Module: diag.laboratory)​

Canonical FHIR resources: ServiceRequest, Specimen, Observation, DiagnosticReport, optional Task
Primary workflows: accessioning; specimen lifecycle; manual entry; verify; release

Database schema (minimum)

  • test_catalog_items: id, tenant_id, name, loinc_code?, specimen_type, payload_json
  • accessions: id, tenant_id, accession_number, patient_id, encounter_id?, priority, created_at
  • specimens: id, tenant_id, accession_id, type_code, status, collected_at?, received_at?, payload_json
  • lab_results: id, tenant_id, accession_id, test_code, status, value_json, entered_by, verified_by?, version

Events

  • diag.lis.events with types: ghasi.lis.accessioned, ...specimen.collected, ...result.verified, ...result.released

4.6 radiology-pacs (Module: diag.radiology)​

Canonical FHIR resources: ImagingStudy, DiagnosticReport, ServiceRequest
Primary workflows: study metadata sync; report lifecycle; viewer launch

Database schema (minimum)

  • pacs_endpoints: id, tenant_id, node_id?, name, qido_url, wado_url, stow_url?, auth_mode, config_json
  • imaging_studies: id, tenant_id, patient_id, encounter_id?, order_id?, started_at, modality, pacs_study_uid, payload_json
  • radiology_reports: id, tenant_id, imaging_study_id, status, authored_at, content, version, payload_json

Events

  • diag.radiology.events with types: ghasi.radiology.study.available, ...report.received, ...report.amended, ...critical.flagged

4.7 Financial Services (Billing / Insurance / Claims)​

These services are designed as workflow orchestrators and integration adapters with FHIR financial resources as canonical meaning.

billing (Module: billing.rcm)​

FHIR resources: Account, ChargeItem, Invoice, PaymentNotice, PaymentReconciliation
Schema (minimum): charges, accounts, invoices, invoice_items, payments, adjustments, price_lists

insurance (Module: billing.insurance)​

FHIR resources: Coverage, CoverageEligibilityRequest/Response
Schema (minimum): coverages, eligibility_transactions, authorizations, payers

claims (Module: billing.claims)​

FHIR resources: Claim, ClaimResponse, ExplanationOfBenefit, PaymentReconciliation
Schema (minimum): claims, claim_submissions, remittances, denial_cases, claim_attachments

5. API Gateway (Kong) Routing (Design)​

The platform continues the Kong gateway model:

  • /v1/* routes to service REST APIs
  • /fhir/R4/* routes to fhir-gateway
  • /interop/hl7v2/* routes to hl7v2-interop (admin + metrics; MLLP is not via Kong)

See API_DOCS.md for the routing table.

6. Implementation Plan (Solution Design View)​

The step-by-step plan is captured in TECHNICAL_REQUIREMENTS.md and the per-module specs. Suggested implementation increments:

  1. FHIR Gateway scaffold + CapabilityStatement
  2. FHIR enablement for core clinical services (read-first, then write)
  3. HL7 v2 engine baseline (ADT + ORU) + message store + dedupe
  4. Add-on services scaffolding + REST + FHIR
  5. Portal (policy-filtered FHIR reads + appointment requests + messaging)
  6. Diagnostic integrations (LIS + PACS adapters)
  7. Financial baseline (billing + insurance + claims) + adapter seams
  8. E2E & contract tests + deployment hardening