Referrals

Trust tier roll-up

RBAC matrix (IC 0–100 scale)

Referral signing hard rule: Only providers (level ≥ 60) can sign an outbound referral. PA/NP (level 60) can draft but require a co-signing physician. RN/MA and ReferralCoordinator can update status and chase acknowledgements but cannot create or sign referrals. FrontDesk can schedule appointments from a referral but cannot modify referral data.

FK Relationship Diagram

erDiagram
    Patient ||--o{ Referral : "subject"
    Provider ||--o{ Referral : "FromProviderID"
    Provider ||--o{ Referral : "ToProviderID"
    Organization ||--o{ Referral : "ToOrganizationID"
    Referral ||--o{ ReferralResponse : "receives"
    Provider ||--o{ ReferralResponse : "RespondingProviderID"
    Referral ||--o{ ReferralStatusHistory : "tracks"
    User ||--o{ ReferralStatusHistory : "ChangedByUserID"
    Patient ||--o{ StandingReferral : "has"
    Provider ||--o{ StandingReferral : "FromProviderID"
    Provider ||--o{ StandingReferral : "ToProviderID"
    

Referral State Machine

stateDiagram-v2
    [*] --> Created
    Created --> Sent : Send via Direct / TEFCA
    Sent --> Acknowledged : Specialist confirms receipt
    Acknowledged --> Scheduled : Appointment booked
    Scheduled --> Completed : Visit completed
    Completed --> ReportReceived : Consultation report returned
    ReportReceived --> [*]
    Created --> Cancelled : Cancel before send
    Sent --> Cancelled : Cancel after send
    Acknowledged --> Cancelled : Cancel after acknowledgment
    Scheduled --> Cancelled : Cancel appointment
    

Functional Requirements

1. P0 The system SHALL allow providers to create outbound referrals with patient demographics, clinical summary, and urgency level.
2. P0 The system SHALL transmit referrals via Direct Messaging or TEFCA endpoints when a DirectAddress or TefcaEndpointUrl is available.
3. P0 The system SHALL track referral status through the full lifecycle (Created through ReportReceived or Cancelled) with immutable history.
4. P0 The system SHALL map referrals to FHIR R4 ServiceRequest resources for interoperability.
5. P1 The system SHALL provide a specialist directory searchable by NPI, specialty, insurance network, and accepting-new-patients status.
6. P1 The system SHALL support standing referrals with configurable visit count limits and expiration dates.
7. P1 The system SHALL auto-decrement VisitCountUsed on StandingReferral when a visit is completed, and alert when approaching the limit.
8. P1 The system SHALL require co-sign from supervising physician when PA/NP drafts a referral.
9. P1 The system SHALL support referral responses (Accepted / Declined / NeedsMoreInfo) from the receiving specialist.
10. P1 The system SHALL notify the referring provider when a consultation report is received.
11. P2 The system SHALL provide a referral coordinator worklist with filtering by urgency, status, and age of referral.
12. P2 The system SHALL allow patients to view their referral status and upcoming specialist appointments via the patient portal.
13. P2 The system SHALL support bulk referral status updates for coordinator efficiency.
14. P2 The system SHALL auto-flag referrals that have been in Sent status for more than 7 days without acknowledgment.

Non-Functional Requirements

• Latency: Direct Message transmission acknowledgment within 60 seconds (99th percentile).
• Availability: Referral submission 99.9% uptime; queued retry for transient Direct/TEFCA failures.
• Interoperability: All referrals representable as FHIR R4 ServiceRequest; USCDI v3 data elements included.
• Audit: Every status transition logged in ReferralStatusHistory; immutable; retained 7 years.
• Encryption: Clinical summary encrypted at rest (AES-256); TLS 1.2+ for Direct messaging.
• Scalability: Support 200 concurrent referral submissions per organization without degradation.
• Directory Freshness: SpecialistDirectory NPI data refreshed from NPPES weekly; stale entries flagged after 90 days.

icApplication Overrides

How the five Referrals AMI schemas turn into a live application: module-specific stack additions (Direct Trust transport, TEFCA participation, NPI registry, payer directories), override component bindings, a versioning worked example, environment cascade, and RBAC enforcement.

Technology stack P0

The shared platform stack (Cosmos DB, Redis, IC-generated API, Angular 21, SQS+SNS, OpenTelemetry, etc.) is documented in the IC Reference. Module-specific additions:

Referrals-specific override bindings P0

These overrides are declared in rules/*.rules.json and replace the default for the matching field name pattern.

Versioning — worked example P0

All referral artifacts are versioned break.feature.bug.buildtimestamp per IC hard rule #9. The example below traces a feature bump on ReferralStatusHistory.

ReferralStatusHistory 1.0.0.20260301T120000Z — Initial schema with StatusString50 and ChangedDateTimeUTC. Component ic-ng21-referral-1-status-pill binds to referral-status-history@1.0.0.* via the DI manifest.

ReferralStatusHistory 1.1.0.20260515T093000Z — feature bump — Adds a single optional field, ChangedByProviderNameString100, to capture the denormalized display name for the provider who changed the referral status. Per the IC change matrix:

Because the change is backward-compatible (optional field addition with no type change to existing fields), the component tag stays ic-ng21-referral-1-status-pill. Existing UI consumers continue to bind referral-status-history@1.x.* and ignore the new field. New UI surfaces that need the provider display name bind referral-status-history@^1.1.0. No new database is required (IC rule #13 only applies to break bumps).

ReferralStatusHistory 2.0.0 — break bump (illustrative) — An illustrative future break bump: StatusString50 splits into StatusCodeString50 + StatusDisplayString100 with multi-language support. Per the IC change matrix this is change field type + add required fields — break bump, EditAMI (90) approval, and per IC rule #13 a new database is provisioned with ETL from the old one. The component tag becomes ic-ng21-referral-2-status-pill; consumers must re-bind. The old database stays live for the configured grace period (default 90 days) for rollback.

Referrals environment details

Referrals RBAC notes

• Referral signing gate. Level ≥ 60 required to finalize outbound referral; level 30 (RN/MA) can draft but not send.
• Coordinator worklist. Level ≥ 30 (RN/MA) can update status; level 20 (FrontDesk) read-only.

Cross-Module Dependencies

• Clinical Documentation — the patient’s global clinical facts (conditions, medications, allergies, lab results, imaging, immunizations, care plans, procedures, vital signs, social history) are maintained in Clinical Doc and consumed by Referrals for USCDI v3 bundle assembly at referral-creation time. Inbound consultation reports are filed back to Clinical Doc as clinical notes.
• Eligibility — provides the patient’s active insurance coverage and network affiliation data used by insurance-aware routing (FR-REF-005). PA flags on referrals are routed to Payer Optimization for concurrent processing.
• Scheduling — when a referral is accepted and the specialist provides an appointment date, the ReferralResponse.AppointmentDateTimeUTC is linked to the Scheduling module for appointment creation. FrontDesk can schedule from the referral context.
• Task Management — stalled referrals (no acknowledgement within threshold), inbound response notifications, and PA-pending alerts create tasks in the provider’s and ReferralCoordinator’s worklists via Task Management.
• Patient Portal — surfaces referral status and appointment details to the patient (FR-REF-006). Patient-facing notifications for key status transitions are delivered through the portal and SMS.
• Payer Optimization — receives PA flags from referrals when insurance-aware routing detects a prior-authorization requirement (FR-REF-012). PA decisions flow back to update the referral’s PA-pending status.
• Data Model — all five referral entities are org-scoped following the operational-is-org-scoped pattern. Clinical facts referenced by USCDI bundles are global following the clinical-facts-are-global pattern.

Cross-Module Links

• Patient Portal — patients view referral status
• Task Management — referral auth tasks route to worklist
• RCM — referral auth status feeds claim submission
• eRx & EPCS — specialist may prescribe post-referral