# athrvas017/medlearn architecture

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

- Interactive diagram: https://gitdiagram.com/athrvas017/medlearn
- Repository: https://github.com/athrvas017/medlearn

## Overview

MedLearn is a medical-education assistant whose main workflow accepts text and/or an image, routes the input through captioning and textbook retrieval as needed, then produces a cited explanation, grounding assessment, and optional quiz. The React interface submits requests to the FastAPI service and presents answers, citations, quizzes, and pipeline progress; Streamlit is an alternative interface. PDF ingestion populates the retrieval store. The README documents several agent transitions; unsampled implementation details and some UI/API wiring are therefore represented only where indexed references or explicit documentation support them.

Main entry points: [`app/graph.py`](https://github.com/athrvas017/medlearn/blob/main/app/graph.py) (LangGraph workflow), [`frontend/src/App.tsx`](https://github.com/athrvas017/medlearn/blob/main/frontend/src/App.tsx) (React workspace), [`app/agents/retriever.py`](https://github.com/athrvas017/medlearn/blob/main/app/agents/retriever.py) (Text retriever), [`app/agents/evaluator.py`](https://github.com/athrvas017/medlearn/blob/main/app/agents/evaluator.py) (Grounding evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_react["React workspace<br/>[App.tsx]"]
  node_input["Question input<br/>[InputBar.tsx]"]
  node_thread["Answer thread<br/>[ChatThread.tsx]"]
  node_atlas["Atlas and quiz<br/>[AtlasSidebar.tsx]"]
  node_progress["Pipeline display"]
  node_api_client["Web API client<br/>[api.ts]"]
  node_streamlit["Streamlit interface<br/>[streamlit_app.py]"]
end

subgraph group_service["API and orchestration"]
  node_fastapi["REST API<br/>[main.py]"]
  node_workflow["LangGraph workflow<br/>[graph.py]"]
  node_state["Agent state<br/>[state.py]"]
end

subgraph group_agents["Education agents"]
  node_router["Input router<br/>[router.py]"]
  node_captioner["Image captioner<br/>[captioner.py]"]
  node_retriever["Text retriever<br/>[retriever.py]"]
  node_explainer["Cited explainer<br/>[explainer.py]"]
  node_quiz["Quiz generator<br/>[quiz_gen.py]"]
end

subgraph group_knowledge["Learning content"]
  node_ingest["PDF ingestion<br/>[ingest.py]"]
  node_store[("Chroma vector store")]
end

subgraph group_evaluation["Quality evaluation"]
  node_evaluator["Grounding evaluator<br/>[evaluator.py]"]
  node_ragas["RAGAS benchmark<br/>[ragas_eval.py]"]
end

node_user(("Learner"))
node_vision["BLIP-2 vision"]
node_gemini["Google Gemini"]

node_user -->|"asks"| node_react
node_react -->|"renders"| node_input
node_react -->|"renders"| node_thread
node_react -->|"renders"| node_atlas
node_react -->|"renders"| node_progress
node_react -->|"calls"| node_api_client
node_input -->|"submits"| node_react
node_api_client -->|"requests"| node_fastapi
node_fastapi -->|"invokes"| node_workflow
node_streamlit -->|"uses"| node_workflow
node_workflow -->|"dispatches"| node_router
node_workflow -->|"dispatches"| node_captioner
node_workflow -->|"dispatches"| node_retriever
node_workflow -->|"dispatches"| node_explainer
node_workflow -->|"dispatches"| node_evaluator
node_workflow -->|"dispatches"| node_quiz
node_workflow -->|"uses"| node_state
node_router -->|"routes images"| node_captioner
node_router -->|"routes text"| node_retriever
node_captioner -->|"adds caption"| node_retriever
node_retriever -->|"provides passages"| node_explainer
node_explainer -->|"sends draft"| node_evaluator
node_evaluator -->|"routes optional quiz"| node_quiz
node_captioner -->|"captions with"| node_vision
node_explainer -->|"generates with"| node_gemini
node_evaluator -->|"scores with"| node_gemini
node_quiz -->|"generates with"| node_gemini
node_retriever -->|"searches"| node_store
node_ingest -->|"populates"| node_store
node_ragas -->|"benchmarks"| node_workflow
node_ragas -->|"uses scoring"| node_evaluator

click node_react "https://github.com/athrvas017/medlearn/blob/main/frontend/src/App.tsx"
click node_input "https://github.com/athrvas017/medlearn/blob/main/frontend/src/components/InputBar.tsx"
click node_thread "https://github.com/athrvas017/medlearn/blob/main/frontend/src/components/ChatThread.tsx"
click node_atlas "https://github.com/athrvas017/medlearn/blob/main/frontend/src/components/AtlasSidebar.tsx"
click node_progress "https://github.com/athrvas017/medlearn/blob/main/frontend/src/components/PipelineStepper.tsx"
click node_api_client "https://github.com/athrvas017/medlearn/blob/main/frontend/src/services/api.ts"
click node_streamlit "https://github.com/athrvas017/medlearn/blob/main/frontend/streamlit_app.py"
click node_fastapi "https://github.com/athrvas017/medlearn/blob/main/app/main.py"
click node_workflow "https://github.com/athrvas017/medlearn/blob/main/app/graph.py"
click node_state "https://github.com/athrvas017/medlearn/blob/main/app/state.py"
click node_router "https://github.com/athrvas017/medlearn/blob/main/app/agents/router.py"
click node_captioner "https://github.com/athrvas017/medlearn/blob/main/app/agents/captioner.py"
click node_retriever "https://github.com/athrvas017/medlearn/blob/main/app/agents/retriever.py"
click node_explainer "https://github.com/athrvas017/medlearn/blob/main/app/agents/explainer.py"
click node_evaluator "https://github.com/athrvas017/medlearn/blob/main/app/agents/evaluator.py"
click node_quiz "https://github.com/athrvas017/medlearn/blob/main/app/agents/quiz_gen.py"
click node_ingest "https://github.com/athrvas017/medlearn/blob/main/app/ingest.py"
click node_store "https://github.com/athrvas017/medlearn/tree/main/app/vectorstore"
click node_ragas "https://github.com/athrvas017/medlearn/blob/main/evals/ragas_eval.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_react,node_input,node_thread,node_atlas,node_progress,node_api_client,node_streamlit toneBlue
class node_fastapi,node_workflow,node_state toneAmber
class node_router,node_captioner,node_retriever,node_explainer,node_quiz toneMint
class node_ingest,node_store toneRose
class node_evaluator,node_ragas,node_user,node_vision,node_gemini toneIndigo
```

## Components

### User interfaces

- [React workspace](https://github.com/athrvas017/medlearn/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Question input](https://github.com/athrvas017/medlearn/blob/main/frontend/src/components/InputBar.tsx): `frontend/src/components/InputBar.tsx`
- [Answer thread](https://github.com/athrvas017/medlearn/blob/main/frontend/src/components/ChatThread.tsx): `frontend/src/components/ChatThread.tsx`
- [Atlas and quiz](https://github.com/athrvas017/medlearn/blob/main/frontend/src/components/AtlasSidebar.tsx): `frontend/src/components/AtlasSidebar.tsx`
- [Pipeline display](https://github.com/athrvas017/medlearn/blob/main/frontend/src/components/PipelineStepper.tsx): `frontend/src/components/PipelineStepper.tsx`
- [Web API client](https://github.com/athrvas017/medlearn/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Streamlit interface](https://github.com/athrvas017/medlearn/blob/main/frontend/streamlit_app.py): `frontend/streamlit_app.py`

### API and orchestration

- [REST API](https://github.com/athrvas017/medlearn/blob/main/app/main.py): `app/main.py`
- [LangGraph workflow](https://github.com/athrvas017/medlearn/blob/main/app/graph.py): `app/graph.py`
- [Agent state](https://github.com/athrvas017/medlearn/blob/main/app/state.py): `app/state.py`

### Education agents

- [Input router](https://github.com/athrvas017/medlearn/blob/main/app/agents/router.py): `app/agents/router.py`
- [Image captioner](https://github.com/athrvas017/medlearn/blob/main/app/agents/captioner.py): `app/agents/captioner.py`
- [Text retriever](https://github.com/athrvas017/medlearn/blob/main/app/agents/retriever.py): `app/agents/retriever.py`
- [Cited explainer](https://github.com/athrvas017/medlearn/blob/main/app/agents/explainer.py): `app/agents/explainer.py`
- [Quiz generator](https://github.com/athrvas017/medlearn/blob/main/app/agents/quiz_gen.py): `app/agents/quiz_gen.py`

### Learning content

- [PDF ingestion](https://github.com/athrvas017/medlearn/blob/main/app/ingest.py): `app/ingest.py`
- [Chroma vector store](https://github.com/athrvas017/medlearn/tree/main/app/vectorstore): `app/vectorstore`

### Quality evaluation

- [Grounding evaluator](https://github.com/athrvas017/medlearn/blob/main/app/agents/evaluator.py): `app/agents/evaluator.py`
- [RAGAS benchmark](https://github.com/athrvas017/medlearn/blob/main/evals/ragas_eval.py): `evals/ragas_eval.py`

### Other components

- **Learner**
- **BLIP-2 vision**
- **Google Gemini**

## Connections

- Learner → React workspace: asks (evidence: `README.md`)
- React workspace → Question input: renders (evidence: `frontend/src/App.tsx`)
- React workspace → Answer thread: renders (evidence: `frontend/src/App.tsx`)
- React workspace → Atlas and quiz: renders (evidence: `frontend/src/App.tsx`)
- React workspace → Pipeline display: renders (evidence: `frontend/src/App.tsx`)
- React workspace → Web API client: calls (evidence: `frontend/src/App.tsx`)
- Question input → React workspace: submits (evidence: `frontend/src/App.tsx`)
- Web API client → REST API: requests (evidence: `README.md`)
- REST API → LangGraph workflow: invokes (evidence: `app/main.py`)
- Streamlit interface → LangGraph workflow: uses (evidence: `README.md`)
- LangGraph workflow → Input router: dispatches (evidence: `app/graph.py`)
- LangGraph workflow → Image captioner: dispatches (evidence: `app/graph.py`)
- LangGraph workflow → Text retriever: dispatches (evidence: `app/graph.py`)
- LangGraph workflow → Cited explainer: dispatches (evidence: `app/graph.py`)
- LangGraph workflow → Grounding evaluator: dispatches (evidence: `app/graph.py`)
- LangGraph workflow → Quiz generator: dispatches (evidence: `app/graph.py`)
- LangGraph workflow → Agent state: uses (evidence: `app/graph.py`)
- Input router → Image captioner: routes images (evidence: `README.md`)
- Input router → Text retriever: routes text (evidence: `README.md`)
- Image captioner → Text retriever: adds caption (evidence: `README.md`)
- Text retriever → Cited explainer: provides passages (evidence: `README.md`)
- Cited explainer → Grounding evaluator: sends draft (evidence: `README.md`)
- Grounding evaluator → Quiz generator: routes optional quiz (evidence: `README.md`)
- Image captioner → BLIP-2 vision: captions with (evidence: `README.md`)
- Cited explainer → Google Gemini: generates with (evidence: `README.md`)
- Grounding evaluator → Google Gemini: scores with (evidence: `app/agents/evaluator.py`)
- Quiz generator → Google Gemini: generates with (evidence: `README.md`)
- Text retriever → Chroma vector store: searches (evidence: `app/agents/retriever.py`)
- PDF ingestion → Chroma vector store: populates (evidence: `README.md`)
- RAGAS benchmark → LangGraph workflow: benchmarks (evidence: `evals/ragas_eval.py`)
- RAGAS benchmark → Grounding evaluator: uses scoring (evidence: `evals/ragas_eval.py`)
