Skip to main content

Platform interoperability — technical requirements

Document version: 1.1
Date: 2026-03-22
Status: Normative companion to SPEC.md

Related documents:

1. Technology stack​

This document inherits the monorepo technology choices and adds/clarifies interoperability tooling.

ComponentTechnologyNotes
LanguageTypeScriptstrict mode; shared DTOs and errors in packages/@ghasi/shared-types
BackendNestJSone process per microservice
FrontendNext.js 16 (App Router)clinician shell + portal route group
UIMUI v6 + EmotionRTL-aware theme; design tokens reused
DatabasePostgreSQL 16per-service isolated DB
CacheRedis 7entitlement cache; FHIR conformance caching; short-lived portal cache
Event BusNATS JetStreamdurable event streams; replay; DLQ
AuthKeycloak (OIDC)JWT via JWKS; patient portal realm/client recommended
API GatewayKong (DB-less)routes /v1/* and /fhir/R4/*
Object StorageMinIOattachments, documents, message attachments
ObservabilityOpenTelemetrytraces across gateway → services → NATS
TestingJest + Supertest + Playwrightunit/integration/contract/E2E

2. Monorepo deliverables​

Add these services under apps/services/:

  • fhir-gateway/
  • hl7v2-interop/
  • immunizations/
  • care-plans-service/
  • messaging/
  • patient-portal-api/
  • laboratory-lis/
  • radiology-pacs/
  • billing/
  • insurance/
  • claims/

2.2 Shared packages (extensions)​

  • packages/@ghasi/event-schemas/: add interop/add-on event types (CloudEvents data payloads)
  • packages/@ghasi/shared-types/: add stable error codes + DTO primitives for add-ons
  • packages/@ghasi/nats-client/: standardize publishing helpers and DLQ patterns
  • packages/@ghasi/auth-guard/ and packages/@ghasi/access-client/: ensure ABAC hooks are available at gateway and service layers

3. API Standards​

3.1 REST (internal product APIs)​

  • Base path: /v1
  • OpenAPI required for each service; routes must be stable and versioned
  • DTO validation:
    • class-validator with strict DTOs
    • return 400 VALIDATION_FAILED with field-level details

3.2 FHIR R4 (interoperability APIs)​

  • Base path: /fhir/R4
  • All FHIR endpoints exposed through fhir-gateway.
  • Minimum interactions per owned resource:
    • read (GET /{ResourceType}/{id})
    • search-type (GET /{ResourceType}?...)
    • create (POST /{ResourceType}) where the module is the system-of-record
    • update (PUT /{ResourceType}/{id}) for mutable facts; immutable facts must use correction patterns

Error format

  • FHIR errors must return OperationOutcome.
  • REST errors must return the platform JSON error envelope:
{
  "error": {
    "code": "SOME_ERROR_CODE",
    "message": "Human readable",
    "details": { "optional": "context" }
  }
}

3.3 Idempotency​

  • REST writes that can be retried MUST support Idempotency-Key.
  • HL7 v2 processing MUST deduplicate by message control ID + sending app/facility + connector.

4. Security​

4.1 Authentication​

  • Kong validates JWT against Keycloak JWKS.
  • Services must also validate JWT (zero-trust).

4.2 Authorization (RBAC + ABAC)​

  • RBAC: Keycloak roles + service-level guards.
  • ABAC: Access Policy service enforcement for patient-linked resources.

Rules:

  • Every request resolves: tenantId + nodeId (hierarchy context).
  • Every patient-linked read/write checks ABAC policy.
  • Patient portal uses separate OAuth client and scopes; never reuse clinician scopes.

4.3 OAuth2 scopes (baseline)​

  • REST scope pattern: svc:{service}:{action} (e.g., svc:orders:write).
  • FHIR scope pattern (SMART-style compatible):
    • Clinician apps: user/*.* + resource-level scopes where required
    • Portal apps: patient/*.* restricted to permitted resources

5. Data & Persistence​

5.1 PostgreSQL conventions​

  • Every table must include: tenant_id, created_at, updated_at, and version for optimistic locking.
  • Use migrations; never rely on TypeORM synchronize in production.

5.2 FHIR storage strategy​

The platform assumes per-service ownership of FHIR resources, exposed via the gateway.

Implementation constraints:

  • Services may store:
    • a canonical relational form, and/or
    • a payload_json column containing a normalized FHIR resource representation
  • Gateway does not persist clinical data.

6. Eventing (NATS JetStream)​

6.1 Envelope​

All new interop and add-on events MUST use the CloudEvents envelope produced by CloudEventsBuilder (see packages/@ghasi/nats-client).

Mandatory fields:

  • id, time, source, type, tenantid, actorid, correlationid, data

6.2 Subject taxonomy​

  • Clinical: clinical.*
  • Diagnostics: diag.*
  • Engagement: engage.*
  • Financial: billing.*
  • Interop: interop.*

6.3 Delivery guarantees​

  • At-least-once delivery; consumers must be idempotent.
  • DLQ is mandatory for interop ingestion pipelines.

7. Interoperability Workflows​

7.1 HL7 v2​

  • Transport: MLLP (TLS where required)
  • Message store must retain raw HL7 payload, parse results, and processing status.

Minimum mappings:

  • ADT A01/A04/A08/A03/A40 → Patient, Encounter (and merges)
  • ORM → ServiceRequest (and order status acknowledgments)
  • ORU → DiagnosticReport + Observation (+ Specimen where provided)

7.2 DICOM/DICOMweb​

  • PACS integration uses DICOMweb (QIDO-RS/WADO-RS) where available.
  • Viewer launch uses signed launch payload; pixel data stays in PACS.

7.3 Payer/EDI​

  • X12 is adapter-based where required; store payload references and acknowledgments.

8. Frontend Integration (Next.js 16)​

8.1 Clinician app pages (additions)​

  • Orders enhancements: ordering for lab/imaging; status tracking; acknowledgments
  • Results viewer enhancements: lab + imaging tabs; released vs unreleased handling
  • Care Plans UI: plan list, plan detail, goals, activities
  • Immunizations UI: history + timeline; record administration; optional forecast indicators
  • Messaging UI: inbox, thread view, compose, read receipts, attachment UI
  • Billing/Insurance/Claims UIs (staff-facing): charge capture, invoice, payment, coverage, claim submission
  • LIS UI: accessioning, specimen status, result entry, verification/release
  • Radiology UI: imaging studies list, report view, viewer launch

8.2 Patient portal pages​

  • Home/summary, appointments, results (released), messages, demographics update requests

9. Testing strategy​

  • Unit tests: domain services, state machines, validation
  • Integration tests: REST + FHIR adapters, NATS publishers/consumers, DB migrations
  • Contract tests:
    • OpenAPI schema validation for REST
    • FHIR interaction conformance for supported resources
  • E2E tests (Playwright): clinician flows + patient portal flows

10. DevOps & Deployment​

  • Update infra/docker-compose.yml to include new services + DBs + NATS streams.
  • Kong declarative config must add:
    • /fhir/R4/* route
    • routes for new /v1/* services
  • CI/CD: per-service workflows aligned to existing monorepo patterns.

11. Step-by-step Implementation Plan (Engineering Tasks)​

Increment 1 — FHIR Gateway Foundation​

  1. Scaffold fhir-gateway with NestJS + auth guards
  2. Implement CapabilityStatement endpoint and resource ownership map
  3. Implement OperationOutcome error mapper and request validation

Increment 2 — FHIR enablement for core clinical services​

  1. Add FHIR controller modules per service for owned resources (read-first)
  2. Implement write interactions where the service is system-of-record
  3. Add conformance tests for each resource/search parameter set

Increment 3 — HL7 v2 Interop Engine​

  1. Scaffold hl7v2-interop + message store
  2. Implement ADT inbound mapping + idempotency
  3. Implement ORU inbound mapping + results ingestion pipeline
  4. Implement ORM outbound hooks from Orders (adapter seam)

Increment 4 — Add-on services (Clinical + Engagement)​

  1. Implement immunizations REST + FHIR
  2. Implement care-plans-service REST + FHIR
  3. Implement messaging REST + FHIR Communication mapping
  4. Implement patient-portal-api policy-filtered reads + scheduling/messaging integration

Increment 5 — Diagnostics add-ons​

  1. Implement laboratory-lis workflows + FHIR mapping
  2. Implement radiology-pacs endpoint registry + viewer launch + imaging metadata

Increment 6 — Financial add-ons​

  1. Implement billing baseline (charges/invoices/payments)
  2. Implement insurance baseline (coverage + eligibility adapter seam)
  3. Implement claims baseline (claim assembly + submission adapter seam)

Increment 7 — UI + E2E​

  1. Add Next.js pages for add-ons + portal route group
  2. Add Playwright E2E suites for core interop and add-on flows

Increment 8 — Hardening​

  1. Performance targets + caching
  2. Observability dashboards
  3. Security review: scopes, ABAC, portal isolation