Referral Module

v1.0.0 · Spring Boot 3.3 · HAPI FHIR 7.4 · Java 21 · Apache 2.0

The AJ FHIR Referral Module is a standalone Spring Boot service that manages cross-facility clinical referrals using FHIR R4 ServiceRequest and Task resources. Before any data is shared with the receiving facility, it verifies patient consent via the Consent Manager.

It runs on port 8083 alongside the AJ FHIR platform.

What it does

GP Practice                              Cardiology Unit
     │                                        │
     │  1. Create draft referral              │
     │  2. POST /api/referrals/{id}/send      │
     │     → Consent gate checks each         │
     │       resource type for receiving      │
     │       facility's client_id             │
     │     → Gate passes → ACTIVE             │
     │     → ServiceRequest + Task → HAPI     │
     │                                        │
     │                          3. GET /api/referrals/inbox
     │                          4. PATCH Task → ACCEPTED
     │                          5. PATCH Task → COMPLETED
     │◄─ referral status updates ─────────────│
     │                                        │
     └──── AuditEvent written async to HAPI ──┘

Key features

Feature	Detail
FHIR ServiceRequest + Task	Full bidirectional sync with HAPI FHIR JPA
Consent gate	Verifies patient consent per resource type before sending
State machine	Validated transitions — invalid moves are rejected with 422
Cross-facility inbox	Receiving facility sees their referral queue
IHE ATNA audit	Every action audited with consent check result
Fail-closed consent	Unreachable Consent Manager → referral blocked, not permitted
Clinician portal	Send, track, and manage referrals

FHIR resources used

Resource	Purpose
ServiceRequest	The referral itself — requester, performer, reason, priority
Task	Workflow steps at the receiving facility — triage, schedule, complete
AuditEvent	IHE ATNA record of every action and consent decision
DocumentReference	Supporting clinical documents attached to the referral
Bundle	Bulk referral export (planned)

Port and integration

The Referral Module runs on port 8083. It depends on three other platform services:

Dependency	Port	Purpose
HAPI FHIR JPA	8080	Canonical ServiceRequest/Task/AuditEvent store
SMART Auth Server	9000	RS256 JWT validation
Consent Manager	8082	Consent gate for cross-facility sharing

What it does not do

The Referral Module manages the workflow and data sharing aspects of referrals. It does not provide scheduling, appointment booking, clinical documentation authoring, or billing integration. It is the consent-enforced routing layer, not an EHR.

---

Next: Quick Start →