# pranjal-kukreja/trialguard architecture

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

- Interactive diagram: https://gitdiagram.com/pranjal-kukreja/trialguard
- Repository: https://github.com/pranjal-kukreja/trialguard

## Overview

TrialGuard is a point-of-care clinical-trial dose-change review system. A researcher submits a proposed action; the backend retrieves patient and protocol context, checks guardrails, obtains parallel compliance, safety, and financial assessments, reduces them to a recommendation, and presents a human decision that is audited. The README documents the domain flow; sampled source and the SOURCE INDEX support selected internal links. Some agent and orchestration internals were not sampled, so those edges rely on README statements rather than inferred code calls.

Main entry points: [`apps/orchestrator/graph.py`](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/graph.py) (Workflow Runtime), [`apps/agent_master/a2a_server.py`](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent_master/a2a_server.py) (Agent Dispatcher), [`apps/gateway/routers/orchestrator.py`](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/gateway/routers/orchestrator.py) (Gateway API), [`apps/web/components/intake-view.tsx`](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/web/components/intake-view.tsx) (Dose Intake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Researcher Experience"]
  node_web_intake["Dose Intake<br/>[intake-view.tsx]"]
  node_gateway["Gateway API<br/>[orchestrator.py]"]
  node_decision_ui["Decision Console"]
end

subgraph group_workflow["Adjudication Workflow"]
  node_orchestrator["Workflow Runtime<br/>[graph.py]"]
  node_protocol["Protocol Analysis<br/>[protocol.py]"]
  node_guardrails["Safety Guardrails<br/>[rule_engine_v3.py]"]
  node_reducer["Consensus Reducer"]
  node_hitl["Human Decision Gate<br/>[hitl.py]"]
  node_audit[("Audit Trail<br/>[audit.py]")]
  node_report["Decision Report"]
  node_state["Shared Workflow State<br/>[state.py]"]
end

subgraph group_specialists["Specialist Reviews"]
  node_master["Agent Dispatcher<br/>[a2a_server.py]"]
  node_compliance["Compliance Agent<br/>[server.py]"]
  node_safety["Safety Agent<br/>[server.py]"]
  node_financial["Financial Agent<br/>[server.py]"]
end

subgraph group_evidence["Clinical Evidence"]
  node_fhir["Patient FHIR<br/>[fhir_client.py]"]
  node_rag["Evidence Pipeline<br/>[pipeline_v3.py]"]
  node_retriever["Trial Retriever<br/>[retriever.py]"]
  node_vector_store[("Vector Store<br/>[vector_store.py]")]
  node_ehr["FHIR EHR<br/>[fhir_client.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"submits action"| node_web_intake
node_web_intake -.->|"sends request"| node_gateway
node_gateway -->|"starts workflow"| node_orchestrator
node_orchestrator -->|"loads patient"| node_fhir
node_fhir -.->|"queries FHIR"| node_ehr
node_orchestrator -->|"checks protocol"| node_protocol
node_orchestrator -->|"checks safety limits"| node_guardrails
node_protocol -.->|"retrieves evidence"| node_rag
node_rag -->|"retrieves clauses"| node_retriever
node_retriever -->|"queries vectors"| node_vector_store
node_orchestrator -->|"dispatches reviews"| node_master
node_master -->|"requests review"| node_compliance
node_master -->|"requests review"| node_safety
node_master -->|"requests review"| node_financial
node_orchestrator -->|"combines verdicts"| node_reducer
node_reducer -->|"offers recommendation"| node_hitl
node_hitl -->|"presents decision"| node_decision_ui
node_researcher -->|"accepts or modifies"| node_decision_ui
node_orchestrator -->|"records decisions"| node_audit
node_gateway -->|"generates report"| node_report
node_orchestrator -->|"uses workflow state"| node_state

click node_web_intake "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/web/components/intake-view.tsx"
click node_gateway "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/gateway/routers/orchestrator.py"
click node_orchestrator "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/graph.py"
click node_fhir "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/fhir_client.py"
click node_protocol "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/protocol.py"
click node_guardrails "https://github.com/pranjal-kukreja/trialguard/blob/main/services/rag_service/src/safety/rule_engine_v3.py"
click node_rag "https://github.com/pranjal-kukreja/trialguard/blob/main/services/rag_service/src/pipeline_v3.py"
click node_retriever "https://github.com/pranjal-kukreja/trialguard/blob/main/services/rag_service/src/rag/retriever.py"
click node_vector_store "https://github.com/pranjal-kukreja/trialguard/blob/main/services/rag_service/src/rag/vector_store.py"
click node_ehr "https://github.com/pranjal-kukreja/trialguard/blob/main/packages/mcp-ehr/src/mcp_ehr/fhir_client.py"
click node_master "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent_master/a2a_server.py"
click node_compliance "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent-compliance/server.py"
click node_safety "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent-safety/server.py"
click node_financial "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent-financial/server.py"
click node_reducer "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/protocol_adjudication.py"
click node_hitl "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/hitl.py"
click node_audit "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/audit.py"
click node_report "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/report_generator.py"
click node_decision_ui "https://github.com/pranjal-kukreja/trialguard/blob/main/apps/web/components/decision-gateway.tsx"
click node_state "https://github.com/pranjal-kukreja/trialguard/blob/main/packages/shared-schemas/shared_schemas/state.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_web_intake,node_gateway,node_decision_ui toneBlue
class node_orchestrator,node_protocol,node_guardrails,node_reducer,node_hitl,node_audit,node_report,node_state toneAmber
class node_master,node_compliance,node_safety,node_financial toneMint
class node_fhir,node_rag,node_retriever,node_vector_store,node_ehr toneRose
class node_researcher toneIndigo
```

## Components

### Researcher Experience

- [Dose Intake](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/web/components/intake-view.tsx): `apps/web/components/intake-view.tsx`
- [Gateway API](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/gateway/routers/orchestrator.py): `apps/gateway/routers/orchestrator.py`
- [Decision Console](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/web/components/decision-gateway.tsx): `apps/web/components/decision-gateway.tsx`

### Adjudication Workflow

- [Workflow Runtime](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/graph.py): `apps/orchestrator/graph.py`
- [Protocol Analysis](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/protocol.py): `apps/orchestrator/nodes/protocol.py`
- [Safety Guardrails](https://github.com/pranjal-kukreja/trialguard/blob/main/services/rag_service/src/safety/rule_engine_v3.py): `services/rag_service/src/safety/rule_engine_v3.py`
- [Consensus Reducer](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/protocol_adjudication.py): `apps/orchestrator/nodes/protocol_adjudication.py`
- [Human Decision Gate](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/hitl.py): `apps/orchestrator/nodes/hitl.py`
- [Audit Trail](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/audit.py): `apps/orchestrator/nodes/audit.py`
- [Decision Report](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/report_generator.py): `apps/orchestrator/report_generator.py`
- [Shared Workflow State](https://github.com/pranjal-kukreja/trialguard/blob/main/packages/shared-schemas/shared_schemas/state.py): `packages/shared-schemas/shared_schemas/state.py`

### Specialist Reviews

- [Agent Dispatcher](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent_master/a2a_server.py): `apps/agent_master/a2a_server.py`
- [Compliance Agent](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent-compliance/server.py): `apps/agent-compliance/server.py`
- [Safety Agent](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent-safety/server.py): `apps/agent-safety/server.py`
- [Financial Agent](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/agent-financial/server.py): `apps/agent-financial/server.py`

### Clinical Evidence

- [Patient FHIR](https://github.com/pranjal-kukreja/trialguard/blob/main/apps/orchestrator/nodes/fhir_client.py): `apps/orchestrator/nodes/fhir_client.py`
- [Evidence Pipeline](https://github.com/pranjal-kukreja/trialguard/blob/main/services/rag_service/src/pipeline_v3.py): `services/rag_service/src/pipeline_v3.py`
- [Trial Retriever](https://github.com/pranjal-kukreja/trialguard/blob/main/services/rag_service/src/rag/retriever.py): `services/rag_service/src/rag/retriever.py`
- [Vector Store](https://github.com/pranjal-kukreja/trialguard/blob/main/services/rag_service/src/rag/vector_store.py): `services/rag_service/src/rag/vector_store.py`
- [FHIR EHR](https://github.com/pranjal-kukreja/trialguard/blob/main/packages/mcp-ehr/src/mcp_ehr/fhir_client.py): `packages/mcp-ehr/src/mcp_ehr/fhir_client.py`

### Other components

- **Researcher**

## Connections

- Researcher → Dose Intake: submits action (evidence: `README.md`)
- Dose Intake → Gateway API: sends request
- Gateway API → Workflow Runtime: starts workflow
- Workflow Runtime → Patient FHIR: loads patient (evidence: `apps/orchestrator/graph.py`)
- Patient FHIR → FHIR EHR: queries FHIR
- Workflow Runtime → Protocol Analysis: checks protocol (evidence: `apps/orchestrator/graph.py`)
- Workflow Runtime → Safety Guardrails: checks safety limits (evidence: `README.md`)
- Protocol Analysis → Evidence Pipeline: retrieves evidence
- Evidence Pipeline → Trial Retriever: retrieves clauses (evidence: `services/rag_service/src/pipeline_v3.py`)
- Trial Retriever → Vector Store: queries vectors (evidence: `services/rag_service/src/rag/retriever.py`)
- Workflow Runtime → Agent Dispatcher: dispatches reviews (evidence: `README.md`)
- Agent Dispatcher → Compliance Agent: requests review (evidence: `README.md`)
- Agent Dispatcher → Safety Agent: requests review (evidence: `README.md`)
- Agent Dispatcher → Financial Agent: requests review (evidence: `README.md`)
- Workflow Runtime → Consensus Reducer: combines verdicts (evidence: `README.md`)
- Consensus Reducer → Human Decision Gate: offers recommendation (evidence: `README.md`)
- Human Decision Gate → Decision Console: presents decision (evidence: `README.md`)
- Researcher → Decision Console: accepts or modifies (evidence: `README.md`)
- Workflow Runtime → Audit Trail: records decisions (evidence: `README.md`)
- Gateway API → Decision Report: generates report (evidence: `apps/gateway/routers/orchestrator.py`)
- Workflow Runtime → Shared Workflow State: uses workflow state (evidence: `apps/orchestrator/graph.py`)
