Platform interoperability — traceability matrix
Document version: 1.1
Date: 2026-03-22
Status: Supplementary; module matrices are authoritative per service
Capability IDs in the tables below use a historical
MVP2-*prefix. That prefix is a stable identifier only — not a delivery phase. Roadmap phases are not tracked in this repository.
Related documents:
- Specification: SPEC.md
- Solution Design: SOLUTION_DESIGN.md
- Technical Requirements: TECHNICAL_REQUIREMENTS.md
- API Documentation: API_DOCS.md
- Event Model: EVENT_MODEL.md
- Licensing module catalogue (codes/deps): ../../modules/licensing/SPEC.md
- FHIR-first Standard (normative): ../platform/FHIR_FIRST_STANDARD.md
1. Purpose
This matrix traces interoperability and add-on capabilities through to:
- Service(s) responsible
- REST and/or FHIR endpoints
- Primary data entities
- Events (NATS JetStream)
- UI surfaces (apps/web)
- Test coverage targets (unit + integration + E2E)
2. Abbreviations
| Abbrev | Meaning |
|---|---|
| FHIR-GW | FHIR Gateway Service (fhir-gateway) |
| HL7 | HL7 v2 Interop Service (hl7v2-interop) |
| IMM | Immunizations Service |
| CP | Care Plans Service |
| MSG | Messaging Service |
| PORT | Patient Portal Service |
| LIS | Laboratory / LIS Service |
| PACS | Radiology / PACS Service |
| BILL | Billing / RCM Service |
| INS | Insurance Service |
| CLM | Claims Service |
| LIC | Licensing enforcement (module entitlements) |
3. Capability traceability
3.1 Interoperability — FHIR Gateway
| ID | Capability | Module Code | Service | Endpoint(s) | Data Entity | Event(s) | UI Surface | Test Targets |
|---|---|---|---|---|---|---|---|---|
| MVP2-FHIR-001 | Consolidated /fhir/R4 entrypoint | ehr.core | FHIR-GW | GET /fhir/R4/metadata | — | fhir.* (optional projections) | — | Contract tests for CapabilityStatement |
| MVP2-FHIR-002 | Resource routing by ownership | ehr.core | FHIR-GW + domain services | GET/POST/PUT /fhir/R4/{Resource} | Per resource owner DB | Cache invalidations as needed | Clinician app uses domain APIs; external uses FHIR | Integration tests for routing matrix |
| MVP2-FHIR-003 | Patient read/search | ehr.registration | FHIR-GW + Registration | GET /fhir/R4/Patient/{id}; GET /fhir/R4/Patient?... | patients | registration.patient.* | Patient banner + portal identity | FHIR read/search tests |
| MVP2-FHIR-004 | Results read/search | ehr.results (+ diag.*) | FHIR-GW + Results/LIS/PACS | GET /fhir/R4/DiagnosticReport?... | results* + LIS/PACS | clinical.results.released, diag.* | Results viewer (clinician + portal) | Release-visibility tests |
3.2 Interoperability — HL7 v2
| ID | Capability | Module Code | Service | Endpoint(s) | Data Entity | Event(s) | UI Surface | Test Targets |
|---|---|---|---|---|---|---|---|---|
| MVP2-HL7-001 | ADT inbound (A01/A04/A08/A40) → FHIR updates | ehr.registration | HL7 + FHIR-GW + Registration | MLLP listener; admin POST /v1/interop/connectors | hl7_messages, hl7_connectors | interop.hl7v2.adt.received | Admin console (optional) | Parser + mapping tests |
| MVP2-HL7-002 | ORM/OML outbound for lab/rad orders | ehr.orders + diag.* | HL7 + Orders | — | hl7_outbox | clinical.orders.placed, interop.hl7v2.orm.sent | Order entry | Event-driven integration tests |
| MVP2-HL7-003 | ORU outbound for released results | ehr.results + diag.* | HL7 + Results/LIS/PACS | — | hl7_outbox | clinical.results.released, interop.hl7v2.oru.sent | Results review | Release workflow tests |
| MVP2-HL7-004 | Message replay + DLQ management | ehr.core | HL7 | GET/POST /v1/interop/messages/* | hl7_messages | dlq.* | Admin console | Retry/DLQ tests |
3.3 Clinical Add-ons
| ID | Capability | Module Code | Service | Endpoint(s) | Data Entity | Event(s) | UI Surface | Test Targets |
|---|---|---|---|---|---|---|---|---|
| MVP2-IMM-001 | Record immunization (administered) | clinical.immunizations | IMM + FHIR-GW | POST /v1/immunizations; POST /fhir/R4/Immunization | immunizations, immunization_lots | clinical.immunizations.recorded | Patient Chart → Immunizations | Unit + REST + FHIR mapping tests |
| MVP2-IMM-002 | Record refusal | clinical.immunizations | IMM | POST /v1/immunizations/{id}/refuse | immunization_refusals | clinical.immunizations.refused | Immunizations | Validation + audit tests |
| MVP2-CP-001 | Create/update care plan | clinical.care-plans | CP + FHIR-GW | POST/PUT /v1/care-plans/careplans; POST/PUT /fhir/R4/CarePlan | care_plans, care_plan_goals | clinical.careplans.created | Care Plans | State machine tests |
| MVP2-CP-002 | Review/sign workflow | clinical.care-plans | CP | POST /v1/care-plans/careplans/{id}/review | care_plan_reviews | clinical.careplans.reviewed | Care Plans | Role-gated tests |
3.4 Engagement Add-ons
| ID | Capability | Module Code | Service | Endpoint(s) | Data Entity | Event(s) | UI Surface | Test Targets |
|---|---|---|---|---|---|---|---|---|
| MVP2-MSG-001 | Staff↔patient secure messaging threads | engage.messaging | MSG | POST /v1/digital-communication/messaging/threads | threads, participants | engage.messaging.* | Inbox | E2E thread + RBAC tests |
| MVP2-MSG-002 | Send/read messages | engage.messaging | MSG | POST /v1/digital-communication/messaging/threads/{id}/messages; POST .../threads/{id}/read | messages, receipts | engage.messaging.message.sent, .read | Inbox + portal messages | Notification tests |
| MVP2-PORT-001 | Portal identity + record summary | engage.patient-portal | PORT (+ FHIR-GW) | GET /v1/portal/me; GET /v1/portal/record/summary | portal_users (or IAM mapping) | portal.notification.queued | Patient Portal | E2E portal auth + summary |
| MVP2-PORT-002 | Portal results visibility rules (released-only) | engage.patient-portal | PORT + Results | GET /v1/portal/results | — | consumes clinical.results.released | Portal results | Policy + ABAC tests |
3.5 Diagnostics Add-ons
| ID | Capability | Module Code | Service | Endpoint(s) | Data Entity | Event(s) | UI Surface | Test Targets |
|---|---|---|---|---|---|---|---|---|
| MVP2-LIS-001 | Accessioning + specimen lifecycle | diag.laboratory | LIS | POST /accessions, POST /specimens, POST /specimens/{id}/receive (no /v1 prefix; Kong) | accessions, specimens | ghasi.lis.accessioned, ghasi.lis.specimen.collected, ghasi.lis.specimen.received | Lab worklist | Workflow tests |
| MVP2-LIS-002 | Result verify/release + chart ingest | diag.laboratory + ehr.results | LIS + Results | POST /results/:id/verify; POST /results/:id/release; Results POST /internal/v1/results/lis-release | lab_results, results | ghasi.lis.result.released → Results ghasi.results.result.* | Results + lab | Idempotent ingest tests |
| MVP2-LIS-003 | HL7 ORU/ORM → LIS domain apply | diag.laboratory | HL7 + LIS | Inbound MLLP; NATS handoff (see HL7V2_LIS_INTEGRATION.md) | lab_results | ghasi.hl7v2.oru_message.received → (planned) LIS consumer | — | Golden ORU + idempotency tests |
| MVP2-PACS-001 | Study availability + report sign | diag.radiology | PACS + Results | GET /v1/radiology/studies*; GET /v1/radiology/studies/{id}/report | imaging_studies, imaging_reports | diag.radiology.study.available, .report.signed | Imaging viewer launch | Viewer launch + auth tests |
3.6 Financial Add-ons
| ID | Capability | Module Code | Service | Endpoint(s) | Data Entity | Event(s) | UI Surface | Test Targets |
|---|---|---|---|---|---|---|---|---|
| MVP2-BILL-001 | Post charges from encounters/orders | billing.rcm | BILL | POST /v1/billing/charges | charges, charge_links | billing.charge.posted | Billing | Ledger tests |
| MVP2-INS-001 | Coverage capture + eligibility check | billing.insurance | INS | POST /v1/insurance/coverage; /eligibility/check | coverages, eligibility_checks | insurance.coverage.created | Registration/Billing | Adapter tests |
| MVP2-CLM-001 | Claim build/validate/submit | billing.claims | CLM | POST /v1/claims/from-encounter/{id}; /submit | claims, claim_lines | claims.submitted | Claims | X12/non-X12 contract tests |
| MVP2-CLM-002 | Remittance ingest + posting | billing.claims | CLM + BILL | POST /v1/claims/remittances/import | remittances, payment_posts | claims.remittance.received | Billing | Reconciliation tests |
4. Licensing Enforcement (Cross-cutting)
| ID | Capability | Module Code(s) | Service | Enforcement Point | Event(s) | UI Surface | Test Targets |
|---|---|---|---|---|---|---|---|
| MVP2-LIC-001 | Module entitlement checks for add-ons | clinical.immunizations, clinical.care-plans, engage.*, diag.*, billing.* | All add-on services | ModuleEntitlementGuard + policy checks | (optional) licensing.* audits | All add-on pages | Guard unit tests + E2E “module disabled” |
5. Notes on Test Implementation
Minimum test coverage expectations:
- Contract tests for
/fhir/R4routing and OperationOutcome mapping - Integration tests for HL7 v2 parsing/mapping and message replay
- E2E tests for portal results visibility and messaging thread flows