# pooja-k-swamy/clinical-protocol-review architecture

> Architecture diagram of the GitHub repository pooja-k-swamy/clinical-protocol-review, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pooja-k-swamy/clinical-protocol-review
- Repository: https://github.com/pooja-k-swamy/clinical-protocol-review

## Overview

#### Purpose and Runtime

Clinical Protocol Draft Assistant is a Python 3.8+ Streamlit application that generates or ingests clinical-trial protocols, obtains LLM-based expert review, and produces amendment-risk findings plus a quality score. It requires an OpenAI API key and uses LangChain-based agent behavior. Primary UI/runtime entry point: `streamlit_app.py`.

#### User Workflow Orchestrator

The Streamlit app is the control plane: users enter study parameters to draft a protocol or upload an existing PDF, TXT, or Markdown document; once protocol text is available, they trigger review and receive consolidated feedback, risk assessment, recommendations, and score.

- `streamlit_app.py`
- `utils/document_processor.py`

#### Protocol Draft Generation

The generation stage turns user-provided study parameters and a guideline template into an initial protocol draft through an LLM. ICH-oriented template content is a key prompt/input boundary rather than application code.

- `agents/protocol_generator.py`
- `templates/ich_templates/ich_template_v1.md`

#### Protocol Content Access Boundary

The MCP-inspired server provides structured protocol access to review agents, intended to expose targeted sections such as objectives or inclusion criteria instead of requiring every agent to process unstructured full text. This is the repository’s abstraction boundary between protocol content and reviewers; the README notes that the MCP model is currently planned for deeper implementation.

- `mcp_interface/protocol_server.py`
- `mcp_interface/review_tools.py`

#### Multi-Agent Clinical Review

Three role-specific LLM agents independently assess the protocol. Their perspectives divide responsibility across scientific rigor/feasibility/safety (PI), site execution and patient management (site physician), and regulatory, ethics, and data integrity (health authority). Their outputs feed the downstream consolidation and risk stages.

- `agents/pi_agent.py`
- `agents/site_physician_agent.py`
- `agents/health_authority_agent.py`

#### Risk and Scoring Pipeline

Consolidated agent feedback is interpreted as potential amendment triggers. The risk assessor emits severity—Low, Medium, or High—along with rationale and recommended remediation. The scoring engine converts identified risk severity into an overall numerical protocol score, where higher indicates fewer or less severe issues.

- `utils/risk_assessor.py`
- `utils/scoring_engine.py`

#### External Dependencies and Boundaries

The system runs locally under Streamlit, with Python dependencies defined in `requirements.txt`. OpenAI is the material external LLM service, configured via `OPENAI_API_KEY`; LangChain mediates agent/LLM behavior. Uploaded documents cross an ingestion boundary at the document processor, while generated and uploaded protocol text converge before MCP-mediated review.

- `requirements.txt`
- `utils/document_processor.py`
- `mcp_interface/protocol_server.py`

Main entry points: [`mcp_interface/review_tools.py`](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/mcp_interface/review_tools.py) (Review tools), [`streamlit_app.py`](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/streamlit_app.py) (Streamlit app), [`agents/protocol_generator.py`](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/protocol_generator.py) (Protocol generator), [`agents/pi_agent.py`](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/pi_agent.py) (PI reviewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit workflow"]
  node_app["Streamlit app<br/>control plane<br/>[streamlit_app.py]"]
  node_upload["Uploaded protocol<br/>input document"]
  node_processor["Document processor<br/>ingestion"]
  node_study_params["Study parameters<br/>user input"]
  node_results["Review results<br/>UI output"]
end

subgraph group_generation["Protocol generation"]
  node_template["ICH guideline template<br/>prompt template<br/>[ich_template_v1.md]"]
  node_generator["Protocol generator<br/>LLM agent"]
end

subgraph group_review["Content access &amp; review"]
  node_protocol["Protocol text<br/>shared artifact"]
  node_protocol_server["Protocol server<br/>MCP-inspired boundary<br/>[protocol_server.py]"]
  node_review_tools["Review tools<br/>structured access<br/>[review_tools.py]"]
  node_pi["PI reviewer<br/>LLM agent<br/>[pi_agent.py]"]
  node_site_physician["Site physician reviewer<br/>LLM agent"]
  node_health_authority["Health authority reviewer<br/>LLM agent"]
end

subgraph group_assessment["Risk &amp; scoring"]
  node_feedback["Consolidated feedback<br/>review artifact"]
  node_risk_assessor["Risk assessor<br/>assessment engine<br/>[risk_assessor.py]"]
  node_scoring["Scoring engine<br/>quality scoring<br/>[scoring_engine.py]"]
end

node_openai{{"OpenAI API<br/>external LLM service"}}
node_dependencies["Python dependencies<br/>runtime dependencies<br/>[requirements.txt]"]

node_app -->|"collects"| node_study_params
node_app -->|"accepts"| node_upload
node_upload -->|"ingests"| node_processor
node_processor -->|"extracts text"| node_protocol
node_study_params -->|"draft inputs"| node_generator
node_template -->|"guides"| node_generator
node_generator -->|"generates"| node_protocol
node_generator -->|"LLM calls"| node_openai
node_protocol -->|"structured access"| node_protocol_server
node_protocol_server -->|"exposes sections"| node_review_tools
node_review_tools -->|"protocol context"| node_pi
node_review_tools -->|"protocol context"| node_site_physician
node_review_tools -->|"protocol context"| node_health_authority
node_pi -->|"LLM calls"| node_openai
node_site_physician -->|"LLM calls"| node_openai
node_health_authority -->|"LLM calls"| node_openai
node_pi -->|"review findings"| node_feedback
node_site_physician -->|"review findings"| node_feedback
node_health_authority -->|"review findings"| node_feedback
node_feedback -->|"assesses triggers"| node_risk_assessor
node_risk_assessor -->|"risk severity"| node_scoring
node_risk_assessor -->|"risk &amp; remediation"| node_results
node_scoring -->|"quality score"| node_results
node_app -->|"displays"| node_results
node_dependencies -.->|"runtime"| node_app

click node_app "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/streamlit_app.py"
click node_processor "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/utils/document_processor.py"
click node_template "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/templates/ich_templates/ich_template_v1.md"
click node_generator "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/protocol_generator.py"
click node_protocol_server "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/mcp_interface/protocol_server.py"
click node_review_tools "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/mcp_interface/review_tools.py"
click node_pi "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/pi_agent.py"
click node_site_physician "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/site_physician_agent.py"
click node_health_authority "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/health_authority_agent.py"
click node_risk_assessor "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/utils/risk_assessor.py"
click node_scoring "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/utils/scoring_engine.py"
click node_dependencies "https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/requirements.txt"

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_app,node_upload,node_processor,node_study_params,node_results toneBlue
class node_template,node_generator toneAmber
class node_protocol,node_protocol_server,node_review_tools,node_pi,node_site_physician,node_health_authority toneMint
class node_feedback,node_risk_assessor,node_scoring toneRose
class node_openai,node_dependencies toneNeutral
```

## Components

### Streamlit workflow

- [Streamlit app](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/streamlit_app.py): control plane · User entry point and workflow orchestrator. · `streamlit_app.py`
- **Uploaded protocol**: input document · PDF, TXT, or Markdown protocol.
- [Document processor](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/utils/document_processor.py): ingestion · Extracts uploaded document text. · `utils/document_processor.py`
- **Study parameters**: user input
- **Review results**: UI output · Feedback, amendment risk, recommendations, and score.

### Protocol generation

- [ICH guideline template](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/templates/ich_templates/ich_template_v1.md): prompt template · `templates/ich_templates/ich_template_v1.md`
- [Protocol generator](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/protocol_generator.py): LLM agent · Drafts a protocol from study parameters and template guidance. · `agents/protocol_generator.py`

### Content access & review

- **Protocol text**: shared artifact · Generated and uploaded protocols converge here.
- [Protocol server](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/mcp_interface/protocol_server.py): MCP-inspired boundary · Provides structured protocol content to reviewers. · `mcp_interface/protocol_server.py`
- [Review tools](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/mcp_interface/review_tools.py): structured access · Exposes targeted protocol sections to agents. · `mcp_interface/review_tools.py`
- [PI reviewer](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/pi_agent.py): LLM agent · Assesses scientific rigor, feasibility, and safety. · `agents/pi_agent.py`
- [Site physician reviewer](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/site_physician_agent.py): LLM agent · Assesses site execution and patient management. · `agents/site_physician_agent.py`
- [Health authority reviewer](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/agents/health_authority_agent.py): LLM agent · Assesses regulatory, ethics, and data integrity concerns. · `agents/health_authority_agent.py`

### Risk & scoring

- **Consolidated feedback**: review artifact
- [Risk assessor](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/utils/risk_assessor.py): assessment engine · Identifies amendment triggers, severity, and remediation. · `utils/risk_assessor.py`
- [Scoring engine](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/utils/scoring_engine.py): quality scoring · Calculates an overall protocol score from risk severity. · `utils/scoring_engine.py`

### Other components

- **OpenAI API**: external LLM service · Configured through OPENAI_API_KEY.
- [Python dependencies](https://github.com/pooja-k-swamy/clinical-protocol-review/blob/main/requirements.txt): runtime dependencies · Defines Streamlit, LangChain, and related packages. · `requirements.txt`

## Connections

- Streamlit app → Study parameters: collects
- Streamlit app → Uploaded protocol: accepts
- Uploaded protocol → Document processor: ingests
- Document processor → Protocol text: extracts text
- Study parameters → Protocol generator: draft inputs
- ICH guideline template → Protocol generator: guides
- Protocol generator → Protocol text: generates
- Protocol generator → OpenAI API: LLM calls
- Protocol text → Protocol server: structured access
- Protocol server → Review tools: exposes sections
- Review tools → PI reviewer: protocol context
- Review tools → Site physician reviewer: protocol context
- Review tools → Health authority reviewer: protocol context
- PI reviewer → OpenAI API: LLM calls
- Site physician reviewer → OpenAI API: LLM calls
- Health authority reviewer → OpenAI API: LLM calls
- PI reviewer → Consolidated feedback: review findings
- Site physician reviewer → Consolidated feedback: review findings
- Health authority reviewer → Consolidated feedback: review findings
- Consolidated feedback → Risk assessor: assesses triggers
- Risk assessor → Scoring engine: risk severity
- Risk assessor → Review results: risk & remediation
- Scoring engine → Review results: quality score
- Streamlit app → Review results: displays
- Python dependencies → Streamlit app: runtime