Build a Care-Team Message Routing Interoperability Sandbox — implementation

## Build
Simulate clinical care-team communication exchanges using standardized HL7 FHIR R5 communication and practitioner metadata. Route automated notification bundles to designated role queues with delivery audit trails.

## User
Health IT Systems Integration Specialist

## Workflow
1. Ingest simulated incoming care-team messages represented as FHIR R5 Communication and MessageHeader structures.
2. Parse practitioner roles and organizational care-team assignments against sandbox endpoint rosters.
3. Execute deterministic priority and on-call routing rules to dispatch messages to recipient queues.
4. Assemble delivery audit logs and emit simulated FHIR CommunicationRequest receipts for integrator review.

## Interface
Web sandbox workspace showing inbound HL7 FHIR payload streams, care-team routing tables, and dispatch logs.

## Data
Generate synthetic FHIR R5 bundles based on official HL7 FHIR R5 Foundation examples without real patient identifiers.
Starter examples below are synthetic. They are not downloaded records.

## Source
[HL7 FHIR overview](https://hl7.org/fhir/overview.html)
Utilize FHIR R5 Foundation module specifications for MessageHeader, Communication, and PractitionerRole reference links.

## Tools
pydantic-ai, fastapi, fhir.resources.
pydantic-ai validates typed FHIR payload attributes and strictly enforces role-based routing schema models.
Local or hosted LLM via API for parsing unstructured care-team escalation text into routing categories.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Validates FHIR R5 Communication and MessageHeader resources using formal schema classes.
- Correctly maps role-based escalation targets (e.g., attending, lab on-call) to simulated queues.
- Outputs a structured routing disposition with timestamp, destination queue, and delivery status.
- Rejects or queues for human review any message with unresolved practitioner references.

## Starter Examples
```json
[
  {
    "input": {
      "message_id": "MSG-9901",
      "resourceType": "Communication",
      "priority": "stat",
      "category": "critical_lab_alert",
      "sender_role": "lab_technician",
      "recipient_role_target": "on_call_attending",
      "payload_text": "Sample critical threshold exceeded for specimen SPEC-421"
    },
    "expected_output": {
      "message_id": "MSG-9901",
      "routing_status": "routed",
      "assigned_queue": "QUEUE_ATTENDING_STAT",
      "dispatch_priority": "high",
      "human_review_required": false
    }
  },
  {
    "input": {
      "message_id": "MSG-9902",
      "resourceType": "Communication",
      "priority": "routine",
      "category": "consult_inquiry",
      "sender_role": "primary_care",
      "recipient_role_target": "unknown_specialist",
      "payload_text": "Requesting chart review for research registry follow-up"
    },
    "expected_output": {
      "message_id": "MSG-9902",
      "routing_status": "exception",
      "assigned_queue": "QUEUE_TRIAGE_ESCALATION",
      "dispatch_priority": "low",
      "human_review_required": true
    }
  }
]
```

## Safety
Sandbox routing emulator for software integration testing; strictly synthetic messages without real patient health information.
Use mock external writes. Require human review before any real deployment.