# kazol196295/medical_report_simplifier architecture

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

- Interactive diagram: https://gitdiagram.com/kazol196295/medical_report_simplifier
- Repository: https://github.com/kazol196295/medical_report_simplifier

## Overview

#### 1. Purpose and Entry Point
This is a session-oriented Streamlit application that converts uploaded medical-report images into OCR text, AI explanations, report-grounded chat answers, and optional clinical-trial matches. The executable UI entry point is `app.py`; it coordinates all processing and stores transient interaction state in the Streamlit session.

Paths: `app.py`, `.streamlit/config.toml`, `.streamlit/secrets.toml.example`

#### 2. Upload and OCR Boundary
Image uploads (JPG/PNG/JPEG/BMP) cross into the local OCR layer, which uses the host-installed Tesseract engine to produce raw report text. OCR is a material local-system dependency and the first transformation boundary: image bytes become text usable by every downstream feature.

Paths: `app.py`, `src/ocr_tesseract.py`, `packages.txt`

#### 3. Report Analysis Agent
The conversational/analysis layer is modeled as a LangGraph state graph. It accepts OCR text, requested analysis mode, and conversation context; selects or invokes analysis tools; and generates explanatory medical content through Groq-hosted LLaMA 3.3-70B. Prompts and structured output expectations are separated from graph control flow.

Paths: `src/langgraph_agent.py`, `src/tools.py`, `src/prompts.py`

#### 4. RAG Index and Report-Grounded Chat
Extracted text is indexed into a FAISS-backed retrieval layer using Hugging Face/Sentence Transformer embeddings. Follow-up chat retrieves semantically relevant report fragments before LLM response generation, creating a grounding boundary between report-specific evidence and the external model. The index is intended to be session-scoped rather than persistent user storage.

Paths: `src/rag_engine.py`, `src/langgraph_agent.py`, `app.py`

#### 5. Patient Profile Extraction
For trial matching, OCR text is transformed into an editable structured patient profile: age, gender, diagnosis, biomarkers, and conditions. This is a separate AI extraction stage so users can review or correct uncertain OCR/LLM-derived fields before they drive external trial queries.

Paths: `src/patient_profiler.py`, `src/prompts.py`, `app.py`

#### 6. Clinical-Trial Search and Matching
The approved profile is sent to the ClinicalTrials.gov API v2 client to find recruiting trials. Trial results are then evaluated for eligibility and presented with matched/unmet criteria. This stage crosses an external public-data boundary; it should tolerate unavailable or sparse API results independently of analysis/chat functionality.

Paths: `src/clinical_trials_api.py`, `src/patient_profiler.py`, `src/tools.py`

#### 7. Runtime and External Dependencies
Runtime is Python 3.9+ with Streamlit as the UI server. Required external services are Groq (API key from Streamlit secrets, environment, or user entry) and ClinicalTrials.gov. Local infrastructure includes Tesseract plus native libraries, FAISS vector search, and model/embedding dependencies. Deployment is compatible with Streamlit Cloud, with OS packages declared separately.

Paths: `requirements.txt`, `runtime.txt`, `packages.txt`

Main entry points: [`src/langgraph_agent.py`](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/langgraph_agent.py) (Analysis agent graph), [`app.py`](https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py) (OCR report text), [`src/ocr_tesseract.py`](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/ocr_tesseract.py) (OCR layer), [`src/clinical_trials_api.py`](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/clinical_trials_api.py) (Trial search and matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit UI"]
  node_streamlit_app["Application<br/>Streamlit entry point<br/>[app.py]"]
  node_session_state[("Session state<br/>transient state<br/>[app.py]")]
  node_uploaded_image["Uploaded report image<br/>image input<br/>[app.py]"]
  node_runtime["Python and deployment runtime<br/>runtime dependencies<br/>[requirements.txt]"]
end

subgraph group_processing["Report Processing"]
  node_ocr_adapter["OCR layer<br/>Tesseract adapter<br/>[ocr_tesseract.py]"]
  node_tesseract{{"Tesseract<br/>local OCR engine<br/>[packages.txt]"}}
  node_report_text["OCR report text<br/>[app.py]"]
  node_agent_graph["Analysis agent graph<br/>LangGraph workflow<br/>[langgraph_agent.py]"]
  node_agent_tools["Analysis tools<br/>tool layer<br/>[tools.py]"]
  node_prompts["Prompts and schemas<br/>prompt definitions<br/>[prompts.py]"]
  node_rag_engine[("Report retrieval<br/>FAISS RAG index<br/>[rag_engine.py]")]
  node_embeddings{{"Embedding models<br/>Sentence Transformer<br/>[rag_engine.py]"}}
end

subgraph group_trials["Trial Matching"]
  node_patient_profiler["Patient profile extraction<br/>AI extraction stage"]
  node_approved_profile["Reviewed patient profile<br/>structured profile<br/>[app.py]"]
  node_trials_client["Trial search and matching<br/>ClinicalTrials client"]
  node_trial_results["Matched trial results<br/>eligibility results<br/>[tools.py]"]
end

subgraph group_external["External Services"]
  node_groq{{"Groq LLaMA<br/>hosted LLM"}}
  node_clinicaltrials_api{{"ClinicalTrials.gov API v2<br/>public trial API"}}
end

node_uploaded_image -->|"upload"| node_streamlit_app
node_streamlit_app -->|"stores workflow state"| node_session_state
node_streamlit_app -->|"submits image"| node_ocr_adapter
node_ocr_adapter -->|"runs OCR"| node_tesseract
node_ocr_adapter -->|"extracts text"| node_report_text
node_report_text -->|"retained per session"| node_session_state
node_report_text -->|"indexes fragments"| node_rag_engine
node_embeddings -->|"embeds text and queries"| node_rag_engine
node_session_state -->|"analysis mode and chat context"| node_agent_graph
node_report_text -->|"report context"| node_agent_graph
node_agent_graph -->|"retrieves chat evidence"| node_rag_engine
node_agent_graph -->|"invokes tools"| node_agent_tools
node_prompts -->|"instructions and output format"| node_agent_graph
node_agent_graph -->|"generates response"| node_groq
node_report_text -->|"extracts fields"| node_patient_profiler
node_prompts -->|"profile schema"| node_patient_profiler
node_patient_profiler -->|"user reviews and edits"| node_approved_profile
node_approved_profile -->|"search criteria"| node_trials_client
node_trials_client -->|"queries recruiting trials"| node_clinicaltrials_api
node_trials_client -->|"evaluates eligibility"| node_trial_results
node_runtime -.->|"hosts application"| node_streamlit_app

click node_streamlit_app "https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py"
click node_session_state "https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py"
click node_uploaded_image "https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py"
click node_ocr_adapter "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/ocr_tesseract.py"
click node_tesseract "https://github.com/kazol196295/medical_report_simplifier/blob/main/packages.txt"
click node_report_text "https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py"
click node_agent_graph "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/langgraph_agent.py"
click node_agent_tools "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/tools.py"
click node_prompts "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/prompts.py"
click node_rag_engine "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/rag_engine.py"
click node_embeddings "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/rag_engine.py"
click node_patient_profiler "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/patient_profiler.py"
click node_approved_profile "https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py"
click node_trials_client "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/clinical_trials_api.py"
click node_trial_results "https://github.com/kazol196295/medical_report_simplifier/blob/main/src/tools.py"
click node_runtime "https://github.com/kazol196295/medical_report_simplifier/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_streamlit_app,node_session_state,node_uploaded_image,node_runtime toneBlue
class node_ocr_adapter,node_tesseract,node_report_text,node_agent_graph,node_agent_tools,node_prompts,node_rag_engine,node_embeddings toneAmber
class node_patient_profiler,node_approved_profile,node_trials_client,node_trial_results toneMint
class node_groq,node_clinicaltrials_api toneRose
```

## Components

### Streamlit UI

- [Application](https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py): Streamlit entry point · Coordinates session-scoped report workflows. · `app.py`
- [Session state](https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py): transient state · Holds OCR text, chat context, and session index. · `app.py`
- [Uploaded report image](https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py): image input · `app.py`
- [Python and deployment runtime](https://github.com/kazol196295/medical_report_simplifier/blob/main/requirements.txt): runtime dependencies · Streamlit, Python 3.9+, native packages, and Python dependencies. · `requirements.txt`

### Report Processing

- [OCR layer](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/ocr_tesseract.py): Tesseract adapter · `src/ocr_tesseract.py`
- [Tesseract](https://github.com/kazol196295/medical_report_simplifier/blob/main/packages.txt): local OCR engine · Host-installed image-to-text dependency. · `packages.txt`
- [OCR report text](https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py): report text · Shared input for analysis, chat, and profiling. · `app.py`
- [Analysis agent graph](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/langgraph_agent.py): LangGraph workflow · Routes analysis and conversational requests. · `src/langgraph_agent.py`
- [Analysis tools](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/tools.py): tool layer · `src/tools.py`
- [Prompts and schemas](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/prompts.py): prompt definitions · Separates medical instructions and structured output expectations. · `src/prompts.py`
- [Report retrieval](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/rag_engine.py): FAISS RAG index · Session-scoped semantic retrieval over report fragments. · `src/rag_engine.py`
- [Embedding models](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/rag_engine.py): Sentence Transformer · `src/rag_engine.py`

### Trial Matching

- [Patient profile extraction](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/patient_profiler.py): AI extraction stage · Produces editable demographics, diagnosis, biomarkers, and conditions. · `src/patient_profiler.py`
- [Reviewed patient profile](https://github.com/kazol196295/medical_report_simplifier/blob/main/app.py): structured profile · User-corrected input for trial queries. · `app.py`
- [Trial search and matching](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/clinical_trials_api.py): ClinicalTrials client · Finds recruiting trials and evaluates criteria. · `src/clinical_trials_api.py`
- [Matched trial results](https://github.com/kazol196295/medical_report_simplifier/blob/main/src/tools.py): eligibility results · Includes matched and unmet criteria. · `src/tools.py`

### External Services

- **Groq LLaMA**: hosted LLM · Generates explanations and grounded answers.
- **ClinicalTrials.gov API v2**: public trial API

## Connections

- Uploaded report image → Application: upload
- Application → Session state: stores workflow state
- Application → OCR layer: submits image
- OCR layer → Tesseract: runs OCR
- OCR layer → OCR report text: extracts text
- OCR report text → Session state: retained per session
- OCR report text → Report retrieval: indexes fragments
- Embedding models → Report retrieval: embeds text and queries
- Session state → Analysis agent graph: analysis mode and chat context
- OCR report text → Analysis agent graph: report context
- Analysis agent graph → Report retrieval: retrieves chat evidence
- Analysis agent graph → Analysis tools: invokes tools
- Prompts and schemas → Analysis agent graph: instructions and output format
- Analysis agent graph → Groq LLaMA: generates response
- OCR report text → Patient profile extraction: extracts fields
- Prompts and schemas → Patient profile extraction: profile schema
- Patient profile extraction → Reviewed patient profile: user reviews and edits
- Reviewed patient profile → Trial search and matching: search criteria
- Trial search and matching → ClinicalTrials.gov API v2: queries recruiting trials
- Trial search and matching → Matched trial results: evaluates eligibility
- Python and deployment runtime → Application: hosts application