# ibrahimango02/healthcare-referral-pipeline architecture

> Architecture diagram of the GitHub repository ibrahimango02/healthcare-referral-pipeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibrahimango02/healthcare-referral-pipeline
- Repository: https://github.com/ibrahimango02/healthcare-referral-pipeline
- Video tour (about a minute): https://gitdiagram.com/ibrahimango02/healthcare-referral-pipeline/video

## Overview

This is a durable clinical-referral intake pipeline: users submit HL7 v2 messages, which are parsed, enriched from clinical notes, validated, optionally held for human review, and written as FHIR R4 resources. The CLI starts and inspects Temporal workflows; the worker registers the workflow and its I/O activities. Activities select LLM or heuristic extraction, local or Lambda validation, and FHIR-server or file output. The README documents these capabilities; unsampled integrations are shown only where that documentation supports them.

Main entry points: [`intake/activities.py`](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/activities.py) (Activity handlers), [`intake/cli.py`](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/cli.py) (Intake CLI), [`intake/workflows.py`](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/workflows.py) (Referral workflow), [`intake/worker.py`](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/worker.py) (Temporal worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Intake interfaces"]
  node_cli["Intake CLI<br/>[cli.py]"]
end

subgraph group_orchestration["Durable orchestration"]
  node_worker["Temporal worker<br/>[worker.py]"]
  node_workflow["Referral workflow<br/>[workflows.py]"]
  node_activities["Activity handlers<br/>[activities.py]"]
  node_models["Workflow data models<br/>[models.py]"]
end

subgraph group_processing["Referral processing"]
  node_parser["HL7 parser<br/>[hl7_parser.py]"]
  node_extractor["Field extraction<br/>[extraction.py]"]
end

subgraph group_outputs["Validation and output"]
  node_validator["Validation rules<br/>[validation.py]"]
  node_fhir["FHIR bundle writer<br/>[fhir.py]"]
end

node_submitter(("Referral submitter"))
node_reviewer(("Human reviewer"))
node_hl7["HL7 message"]
node_temporal[("Temporal service")]
node_anthropic["Anthropic API"]
node_lambda["AWS Lambda validation<br/>[lambda_handler.py]"]
node_fhirserver[("FHIR R4 server")]
node_bundlefile["Bundle file output"]

node_submitter -->|"submits message"| node_cli
node_hl7 -->|"provides contents"| node_cli
node_cli -->|"reads control ID"| node_parser
node_cli -->|"starts or queries"| node_temporal
node_worker -->|"connects and polls"| node_temporal
node_worker -->|"registers workflow"| node_workflow
node_worker -->|"registers activities"| node_activities
node_temporal -->|"dispatches workflow"| node_workflow
node_workflow -->|"schedules steps"| node_activities
node_workflow -->|"uses typed data"| node_models
node_activities -->|"calls parse"| node_parser
node_activities -->|"calls extraction"| node_extractor
node_activities -->|"calls local rules"| node_validator
node_activities -.->|"invokes optionally"| node_lambda
node_lambda -->|"calls shared rules"| node_validator
node_activities -->|"calls write"| node_fhir
node_extractor -.->|"requests extraction"| node_anthropic
node_reviewer -->|"submits decision"| node_cli
node_cli -->|"signals review"| node_temporal
node_fhir -.->|"posts transaction"| node_fhirserver
node_fhir -->|"writes bundle"| node_bundlefile

click node_cli "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/cli.py"
click node_worker "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/worker.py"
click node_workflow "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/workflows.py"
click node_activities "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/activities.py"
click node_models "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/models.py"
click node_parser "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/hl7_parser.py"
click node_extractor "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/extraction.py"
click node_validator "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/validation.py"
click node_lambda "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/lambda_handler.py"
click node_fhir "https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/fhir.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_reviewer toneBlue
class node_worker,node_workflow,node_activities,node_models,node_temporal,node_fhirserver toneAmber
class node_parser,node_extractor,node_anthropic toneMint
class node_validator,node_fhir toneRose
class node_submitter,node_hl7,node_bundlefile toneIndigo
class node_lambda toneTeal
```

## Components

### Intake interfaces

- [Intake CLI](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/cli.py): `intake/cli.py`

### Durable orchestration

- [Temporal worker](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/worker.py): `intake/worker.py`
- [Referral workflow](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/workflows.py): `intake/workflows.py`
- [Activity handlers](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/activities.py): `intake/activities.py`
- [Workflow data models](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/models.py): `intake/models.py`

### Referral processing

- [HL7 parser](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/hl7_parser.py): `intake/hl7_parser.py`
- [Field extraction](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/extraction.py): `intake/extraction.py`

### Validation and output

- [Validation rules](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/validation.py): `intake/validation.py`
- [FHIR bundle writer](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/intake/fhir.py): `intake/fhir.py`

### Other components

- **Referral submitter**
- **Human reviewer**
- **HL7 message**
- **Temporal service**
- **Anthropic API**
- [AWS Lambda validation](https://github.com/ibrahimango02/healthcare-referral-pipeline/blob/main/lambda_handler.py): `lambda_handler.py`
- **FHIR R4 server**
- **Bundle file output**

## Connections

- Referral submitter → Intake CLI: submits message
- HL7 message → Intake CLI: provides contents
- Intake CLI → HL7 parser: reads control ID
- Intake CLI → Temporal service: starts or queries
- Temporal worker → Temporal service: connects and polls
- Temporal worker → Referral workflow: registers workflow
- Temporal worker → Activity handlers: registers activities
- Temporal service → Referral workflow: dispatches workflow
- Referral workflow → Activity handlers: schedules steps
- Referral workflow → Workflow data models: uses typed data
- Activity handlers → HL7 parser: calls parse
- Activity handlers → Field extraction: calls extraction
- Activity handlers → Validation rules: calls local rules
- Activity handlers → AWS Lambda validation: invokes optionally
- AWS Lambda validation → Validation rules: calls shared rules
- Activity handlers → FHIR bundle writer: calls write
- Field extraction → Anthropic API: requests extraction
- Human reviewer → Intake CLI: submits decision
- Intake CLI → Temporal service: signals review
- FHIR bundle writer → FHIR R4 server: posts transaction
- FHIR bundle writer → Bundle file output: writes bundle