# akkisensei/triagerag architecture

> Architecture diagram of the GitHub repository akkisensei/triagerag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akkisensei/triagerag
- Repository: https://github.com/akkisensei/triagerag

## Overview

TriageRAG is a synthetic-data emergency-triage research prototype: deterministic code makes safety decisions, while a constrained generator drafts protocol-based actions that are machine-verified. The main workflow evaluates patient state, retrieves population-aware protocol evidence, drafts and verifies a plan, then produces a verdict and audit record. The graph also preserves protocol ingestion and the API/web surfaces. Some UI-to-API and route-to-workflow wiring is not shown in the sampled evidence, so those connections are omitted.

Main entry points: [`src/triagerag/orchestrator.py`](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/orchestrator.py) (Triage workflow), [`src/triagerag/engine/rule_engine.py`](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/rule_engine.py) (Rule evaluation), [`src/triagerag/rag/service.py`](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/service.py) (Patient-aware retrieval), [`src/triagerag/llm/draft.py`](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/llm/draft.py) (Plan drafting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Inputs and contracts"]
  node_contracts["Patient contracts<br/>[schemas.py]"]
  node_normalization["Input normalization<br/>[validators.py]"]
  node_orchestrator["Triage workflow<br/>[orchestrator.py]"]
end

subgraph group_safety["Deterministic safety"]
  node_registry[("Clinical registry<br/>[registry.py]")]
  node_rules["Rule evaluation<br/>[rule_engine.py]"]
  node_dosing["Dose calculation<br/>[dose_engine.py]"]
  node_scores["Physiology scoring<br/>[scores.py]"]
  node_verdict["Safety verdict<br/>[verdict.py]"]
end

subgraph group_retrieval["Protocol evidence"]
  node_ingestion["Protocol ingestion<br/>[ingest.py]"]
  node_chunking["Decision chunking<br/>[chunking.py]"]
  node_index[("Retrieval index<br/>[index.py]")]
  node_retrieval_service["Patient-aware retrieval<br/>[service.py]"]
end

subgraph group_planning["Plan and audit"]
  node_drafting["Plan drafting<br/>[draft.py]"]
  node_mock_llm["Deterministic mock<br/>[fake.py]"]
  node_verification["Plan verification<br/>[plan_verifier.py]"]
  node_audit[("Audit chain<br/>[chain.py]")]
end

subgraph group_surfaces["User surfaces"]
  node_web["Web interface<br/>[App.tsx]"]
  node_api["HTTP API<br/>[app.py]"]
end

node_clinician(("Triage user"))

node_clinician -.->|"submits case"| node_web
node_web -.->|"sends requests"| node_api
node_api -.->|"runs triage"| node_orchestrator
node_orchestrator -->|"validates input"| node_normalization
node_orchestrator -->|"evaluates rules"| node_rules
node_orchestrator -->|"computes scores"| node_scores
node_orchestrator -->|"resolves verdict"| node_verdict
node_rules -->|"reads rules"| node_registry
node_rules -->|"checks doses"| node_dosing
node_orchestrator -->|"retrieves evidence"| node_retrieval_service
node_retrieval_service -->|"searches index"| node_index
node_ingestion -->|"parses protocols"| node_chunking
node_orchestrator -->|"requests draft"| node_drafting
node_drafting -.->|"generates draft"| node_mock_llm
node_orchestrator -->|"verifies plan"| node_verification
node_orchestrator -->|"records assessment"| node_audit
node_contracts -.->|"defines payloads"| node_orchestrator
node_orchestrator -->|"Pass 1 safety"| node_rules
node_rules -->|"conditions retrieval"| node_retrieval_service
node_retrieval_service -->|"supplies evidence"| node_drafting
node_drafting -->|"submits plan"| node_verification
node_verification -.->|"verified result"| node_audit

click node_web "https://github.com/akkisensei/triagerag/blob/main/web/src/App.tsx"
click node_api "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/api/app.py"
click node_contracts "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/contracts/schemas.py"
click node_normalization "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/normalize/validators.py"
click node_orchestrator "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/orchestrator.py"
click node_registry "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/registry.py"
click node_rules "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/rule_engine.py"
click node_dosing "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/dose_engine.py"
click node_scores "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/scores.py"
click node_verdict "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/verdict.py"
click node_ingestion "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/ingest.py"
click node_chunking "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/chunking.py"
click node_index "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/index.py"
click node_retrieval_service "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/service.py"
click node_drafting "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/llm/draft.py"
click node_mock_llm "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/llm/fake.py"
click node_verification "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/verify/plan_verifier.py"
click node_audit "https://github.com/akkisensei/triagerag/blob/main/src/triagerag/audit/chain.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_contracts,node_normalization,node_orchestrator,node_clinician toneBlue
class node_registry,node_rules,node_dosing,node_scores,node_verdict toneAmber
class node_ingestion,node_chunking,node_index,node_retrieval_service toneMint
class node_drafting,node_mock_llm,node_verification,node_audit toneRose
class node_web,node_api toneIndigo
```

## Components

### Inputs and contracts

- [Patient contracts](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/contracts/schemas.py): `src/triagerag/contracts/schemas.py`
- [Input normalization](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/normalize/validators.py): `src/triagerag/normalize/validators.py`
- [Triage workflow](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/orchestrator.py): `src/triagerag/orchestrator.py`

### Deterministic safety

- [Clinical registry](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/registry.py): `src/triagerag/engine/registry.py`
- [Rule evaluation](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/rule_engine.py): `src/triagerag/engine/rule_engine.py`
- [Dose calculation](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/dose_engine.py): `src/triagerag/engine/dose_engine.py`
- [Physiology scoring](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/scores.py): `src/triagerag/engine/scores.py`
- [Safety verdict](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/engine/verdict.py): `src/triagerag/engine/verdict.py`

### Protocol evidence

- [Protocol ingestion](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/ingest.py): `src/triagerag/rag/ingest.py`
- [Decision chunking](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/chunking.py): `src/triagerag/rag/chunking.py`
- [Retrieval index](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/index.py): `src/triagerag/rag/index.py`
- [Patient-aware retrieval](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/rag/service.py): `src/triagerag/rag/service.py`

### Plan and audit

- [Plan drafting](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/llm/draft.py): `src/triagerag/llm/draft.py`
- [Deterministic mock](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/llm/fake.py): `src/triagerag/llm/fake.py`
- [Plan verification](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/verify/plan_verifier.py): `src/triagerag/verify/plan_verifier.py`
- [Audit chain](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/audit/chain.py): `src/triagerag/audit/chain.py`

### User surfaces

- [Web interface](https://github.com/akkisensei/triagerag/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [HTTP API](https://github.com/akkisensei/triagerag/blob/main/src/triagerag/api/app.py): `src/triagerag/api/app.py`

### Other components

- **Triage user**

## Connections

- Triage user → Web interface: submits case
- Web interface → HTTP API: sends requests
- HTTP API → Triage workflow: runs triage
- Triage workflow → Input normalization: validates input (evidence: `src/triagerag/orchestrator.py`)
- Triage workflow → Rule evaluation: evaluates rules (evidence: `src/triagerag/orchestrator.py`)
- Triage workflow → Physiology scoring: computes scores (evidence: `src/triagerag/orchestrator.py`)
- Triage workflow → Safety verdict: resolves verdict (evidence: `src/triagerag/orchestrator.py`)
- Rule evaluation → Clinical registry: reads rules (evidence: `src/triagerag/engine/rule_engine.py`)
- Rule evaluation → Dose calculation: checks doses (evidence: `src/triagerag/engine/rule_engine.py`)
- Triage workflow → Patient-aware retrieval: retrieves evidence (evidence: `src/triagerag/orchestrator.py`)
- Patient-aware retrieval → Retrieval index: searches index (evidence: `src/triagerag/rag/service.py`)
- Protocol ingestion → Decision chunking: parses protocols (evidence: `src/triagerag/rag/ingest.py`)
- Triage workflow → Plan drafting: requests draft (evidence: `src/triagerag/orchestrator.py`)
- Plan drafting → Deterministic mock: generates draft
- Triage workflow → Plan verification: verifies plan (evidence: `src/triagerag/orchestrator.py`)
- Triage workflow → Audit chain: records assessment (evidence: `src/triagerag/orchestrator.py`)
- Patient contracts → Triage workflow: defines payloads (evidence: `src/triagerag/orchestrator.py`)
- Triage workflow → Rule evaluation: Pass 1 safety (evidence: `src/triagerag/orchestrator.py`)
- Rule evaluation → Patient-aware retrieval: conditions retrieval
- Patient-aware retrieval → Plan drafting: supplies evidence
- Plan drafting → Plan verification: submits plan
- Plan verification → Audit chain: verified result
