Platform interoperability & extensions — specification

Document version: 1.1
Date: 2026-03-22
Status: Normative (module specs prevail where they differ)

Baseline: The shipped repository is the product baseline. Phased roadmap labels (historical “MVP0/1/2”) are not used for delivery tracking; use per-module specs and ../../_generation/SERVICE_BASELINE_AUDIT_TRACKER.md.

1. Business Context

This document defines Ghasi EHR’s FHIR-first interoperability surface and licensed add-on modules required for end-to-end delivery in typical deployments:

Standards-based exchange (FHIR R4 REST) across core and add-on modules
HL7 v2 interoperability workflows for ADT / ORM / ORU
Diagnostic add-ons (Laboratory/LIS, Radiology/PACS integration)
Engagement add-ons (Messaging/Notifications, Patient Portal, Virtual Care / telehealth)
Financial add-ons (Billing, Insurance, Claims)

This layer does not replace existing /v1/* REST APIs; it adds a FHIR R4 API surface and integration workflows while keeping UI/product APIs stable.

2. Scope

2.1 In Scope

A) Web application (core + add-ons)

A single Next.js 16 application with:
- Core clinical shell
- Add-on module navigation entries and pages
- Patient portal experience (separate route group with patient-facing auth)

B) Add-on microservices (NestJS) The following optional licensed add-ons are modeled as independent services:

Domain	Service	Module Code (Licensing)
Clinical	`immunizations`	`clinical.immunizations`
Clinical	`care-plans-service`	`clinical.care-plans`
Engagement	`messaging` (includes PHI-safe notifications hooks)	`engage.messaging`
Engagement	`patient-portal-api` (or portal API slice in web backend if deployed as BFF)	`engage.patient-portal`
Engagement	`virtual-care-service`	`engage.virtual-care`
Diagnostic	`laboratory-lis`	`diag.laboratory`
Diagnostic	`radiology-pacs`	`diag.radiology`
Billing	`billing`	`billing.rcm`
Billing	`insurance`	`billing.insurance`
Billing	`claims`	`billing.claims`

C) REST + FHIR APIs per microservice

All core clinical and platform services SHOULD expose (where applicable):
- Internal REST APIs for UI/product workflows (existing /v1/*)
- FHIR R4 interactions for clinically meaningful facts they own (see §6)

D) FHIR Gateway Service

Introduce a dedicated fhir-gateway that:
- Publishes a consolidated CapabilityStatement
- Provides a single FHIR base endpoint for clients
- Routes/aggregates requests to the owning microservice(s)
- Applies tenant isolation and access policy at the FHIR boundary

E) HL7 v2 Interop Engine

Introduce a dedicated hl7v2-interop to support:
- ADT inbound feeds (A01/A04/A08/A03/A40)
- ORM/ACK ordering exchange
- ORU result ingestion
HL7 v2 messages are mapped into canonical FHIR R4 resources per ../platform/FHIR_FIRST_STANDARD.md

F) Event-driven communication

Use NATS JetStream for domain/integration events.
Standardize on CloudEvents envelope for all new events.

G) Multi-tenant + license-based activation

All add-on modules MUST enforce entitlement at runtime via the platform licensing/entitlement mechanism.

2.2 Out of scope

Advanced analytics/BI dashboards (future)
Full national Implementation Guides (IGs) or country certifications unless explicitly contracted
Full RCM denials automation and appeals automation beyond baseline workflows
Deep ERP integrations beyond adapter interfaces
UI Design System module and service.

3. Repository baseline

Interoperability and add-on capabilities are implemented incrementally in the monorepo. Gaps versus this document and module specs are tracked in ../../_generation/SERVICE_BASELINE_AUDIT_TRACKER.md.

4. Actors and roles (extensions)

Actor	Description
Patient	Uses Patient Portal to view permitted record items, appointments, results (released), and messaging.
Biller / Cashier	Manages charges, invoices, payments, statements.
Claims Specialist	Prepares/submits claims, tracks status, posts remittances, manages denials.
Insurance Coordinator	Captures coverage, runs eligibility checks, manages prior authorizations.
Lab Technician / Lab Supervisor	Accessioning, specimen tracking, result entry/verification/release.
Radiology Tech / Radiologist	Imaging study/report availability, prelim/final/amended report lifecycle.
Integration Analyst	Configures HL7 v2 endpoints, routing, mappings, partner adapters.

All actors defined in core requirements and module specs remain in scope.

5. Functional deliverables (cross-cutting)

5.1 FHIR R4 API Baseline (All Services)

FR-FHIR-001: Provide a FHIR R4 base endpoint via fhir-gateway.
FR-FHIR-002: Publish a consolidated CapabilityStatement declaring supported resources/interactions/search parameters.
FR-FHIR-003: Enforce tenant isolation and access policy (RBAC + ABAC) on all FHIR interactions.
FR-FHIR-004: Support stable identifiers, provenance metadata, and correction/amendment semantics per module.
FR-FHIR-005: Provide deterministic pagination and safe search behavior.

5.2 HL7 v2 Interoperability Baseline

FR-V2-001: Support ADT inbound messages and map to Patient + Encounter updates.
FR-V2-002: Support ORM outbound (orders) and ORU inbound (results) workflows, preserving message identifiers for deduplication.
FR-V2-003: Maintain an immutable message log with processing status and correlation to created/updated FHIR resources.

5.3 Licensed Add-ons

Add-on module functional requirements are defined in the corresponding module specifications (see links above). Implementations include, for example:
- Immunizations recording (+ optional forecasting hooks)
- Care Plans (CarePlan/Goal lifecycle)
- Messaging (Communication + PHI-safe notification hooks)
- Patient Portal (policy-filtered reads + appointment requests)
- LIS (accession/specimen/result verification)
- Radiology/PACS integration (ImagingStudy metadata + viewer launch)
- Billing, Insurance, Claims baseline workflows

6. FHIR resource ownership

To keep microservices independent while maintaining a cohesive FHIR surface, resource ownership rules are:

Resource Type	Primary Owner	Notes
`Patient`, `Encounter`, `RelatedPerson`	Registration	ADT updates flow here via interop engine.
`Appointment`, `Schedule`, `Slot`	Scheduling	Portal appointment requests write to Scheduling workflow.
`Practitioner`, `PractitionerRole`, `Organization`, `Endpoint`	Provider Directory	Includes endpoints for interop discovery where applicable.
`Location`	Facility	Facility/location data for scheduling/encounters.
`AllergyIntolerance`	Allergies
`Condition`	Problem List
`Observation` (vital-signs)	Vitals	Must declare `category=vital-signs`.
`MedicationRequest`, `MedicationAdministration*`	Medication Management	`MedicationStatement` optional by deployment.
`ServiceRequest`	Orders/CPOE	Includes lab/radiology ordering.
`DiagnosticReport`	Results	Lab/imaging reports; category used to distinguish.
`Observation` (laboratory)	Results (via LIS)	LIS may author; Results owns the released clinical facts.
`Specimen`	Laboratory/LIS	Source-of-truth for specimen tracking.
`ImagingStudy`	Radiology/PACS	Pixel data remains in PACS; store references.
`Immunization`, `ImmunizationRecommendation`	Immunizations
`CarePlan`, `Goal`, `Task*`	Care Plans	`Task` optional for activity tracking.
`Communication`	Messaging	Patient-linked messages policy-filtered.
Financial resources (`Account`, `ChargeItem`, `Invoice`, `Claim`, `Coverage`, etc.)	Billing/Insurance/Claims	Adapter-driven for X12 / payer-specific formats.

* indicates optional interactions depending on deployment licensing and workflow scope.

7. Acceptance criteria

Services that own clinical facts SHOULD expose FHIR R4 interactions for those resources through fhir-gateway per module spec.
HL7 v2 ADT + ORU + ORM workflows can be demonstrated end-to-end in a local environment.
Add-on modules can be enabled/disabled per node via licensing and enforce entitlement at runtime.
Web UI includes pages for add-on modules and a patient portal route group.

8. Open questions

OQ-INT-001: Will the FHIR surface be backed by a centralized FHIR persistence layer, or purely by per-service stores exposed through the gateway? (This spec assumes per-service ownership with gateway routing/aggregation.)
OQ-INT-002: Which HL7 v2 transport modes are required first (MLLP only vs. also file-drop/SFTP)?
OQ-INT-003: For UAE, which authority and e-claims formats are in scope (impacts Claims/Insurance adapters)?

1. Business Context​

2. Scope​

2.1 In Scope​

2.2 Out of scope​

3. Repository baseline​

4. Actors and roles (extensions)​

5. Functional deliverables (cross-cutting)​

5.1 FHIR R4 API Baseline (All Services)​

5.2 HL7 v2 Interoperability Baseline​

5.3 Licensed Add-ons​

6. FHIR resource ownership​

7. Acceptance criteria​

8. Open questions​