# ph-tejas/medassist---ai-patient-document-assistant architecture

> Architecture diagram of the GitHub repository ph-tejas/medassist---ai-patient-document-assistant, 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/ph-tejas/medassist---ai-patient-document-assistant
- Repository: https://github.com/ph-tejas/medassist---ai-patient-document-assistant

## Overview

MedAssist is a medical-document question-answering API. Users register or log in, upload PDFs, and ask questions about their documents; the API extracts and stores text, indexes chunks for retrieval, and uses retrieved context to generate answers. Separate branches cover authenticated document listing and retrieval/answer evaluation. The excerpts show the main call paths; integrations and persistence are represented where their use is explicit.

Main entry points: [`MedAssist/app/main.py`](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/main.py) (HTTP API), [`MedAssist/app/retrieval.py`](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/retrieval.py) (Embedding search), [`MedAssist/app/evaluate.py`](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/evaluate.py) (RAG evaluation), [`MedAssist/app/database.py`](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/database.py) (Document and chunk storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflows"]
  node_api["HTTP API<br/>[main.py]"]
end

subgraph group_identity["Identity"]
  node_auth["Authentication<br/>[auth.py]"]
  node_identity_data[("User records<br/>[database.py]")]
end

subgraph group_documents["Document retrieval"]
  node_pdf["PDF extraction<br/>[pdf_utils.py]"]
  node_chunker["Text chunking<br/>[chunker.py]"]
  node_retrieval["Embedding search<br/>[retrieval.py]"]
  node_document_data[("Document and chunk storage<br/>[database.py]")]
end

subgraph group_answering["Answer generation"]
  node_answer["Answer generation<br/>[llm.py]"]
  node_evaluation["RAG evaluation<br/>[evaluate.py]"]
end

node_user(("User"))
node_ollama["Ollama service"]
node_mysql[("MySQL")]
node_embedding_model["Sentence Transformers"]
node_faiss["FAISS index"]

node_user -->|"sends requests"| node_api
node_api -->|"hashes and verifies"| node_auth
node_api -->|"reads and creates users"| node_identity_data
node_api -->|"lists and saves documents"| node_document_data
node_api -->|"extracts PDF text"| node_pdf
node_api -->|"indexes and retrieves"| node_retrieval
node_api -->|"generates answers"| node_answer
node_retrieval -->|"chunks text"| node_chunker
node_retrieval -->|"stores and loads chunks"| node_document_data
node_retrieval -->|"embeds text"| node_embedding_model
node_retrieval -->|"builds and searches"| node_faiss
node_answer -->|"requests completion"| node_ollama
node_identity_data -->|"queries and writes"| node_mysql
node_document_data -->|"queries and writes"| node_mysql
node_evaluation -->|"tests chunking"| node_chunker
node_evaluation -->|"measures retrieval"| node_retrieval
node_evaluation -->|"measures answers"| node_answer

click node_api "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/main.py"
click node_auth "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/auth.py"
click node_identity_data "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/database.py"
click node_pdf "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/pdf_utils.py"
click node_chunker "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/chunker.py"
click node_retrieval "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/retrieval.py"
click node_document_data "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/database.py"
click node_answer "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/llm.py"
click node_evaluation "https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/evaluate.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_api,node_user toneBlue
class node_auth,node_identity_data,node_mysql toneAmber
class node_pdf,node_chunker,node_retrieval,node_document_data toneMint
class node_answer,node_evaluation toneRose
class node_ollama,node_embedding_model,node_faiss toneIndigo
```

## Components

### API workflows

- [HTTP API](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/main.py): `MedAssist/app/main.py`

### Identity

- [Authentication](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/auth.py): `MedAssist/app/auth.py`
- [User records](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/database.py): `MedAssist/app/database.py`

### Document retrieval

- [PDF extraction](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/pdf_utils.py): `MedAssist/app/pdf_utils.py`
- [Text chunking](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/chunker.py): `MedAssist/app/chunker.py`
- [Embedding search](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/retrieval.py): `MedAssist/app/retrieval.py`
- [Document and chunk storage](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/database.py): `MedAssist/app/database.py`

### Answer generation

- [Answer generation](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/llm.py): `MedAssist/app/llm.py`
- [RAG evaluation](https://github.com/ph-tejas/medassist---ai-patient-document-assistant/blob/main/MedAssist/app/evaluate.py): `MedAssist/app/evaluate.py`

### Other components

- **User**
- **Ollama service**
- **MySQL**
- **Sentence Transformers**
- **FAISS index**

## Connections

- User → HTTP API: sends requests (evidence: `MedAssist/app/main.py`)
- HTTP API → Authentication: hashes and verifies (evidence: `MedAssist/app/main.py`)
- HTTP API → User records: reads and creates users (evidence: `MedAssist/app/main.py`)
- HTTP API → Document and chunk storage: lists and saves documents (evidence: `MedAssist/app/main.py`)
- HTTP API → PDF extraction: extracts PDF text (evidence: `MedAssist/app/main.py`)
- HTTP API → Embedding search: indexes and retrieves (evidence: `MedAssist/app/main.py`)
- HTTP API → Answer generation: generates answers (evidence: `MedAssist/app/main.py`)
- Embedding search → Text chunking: chunks text (evidence: `MedAssist/app/retrieval.py`)
- Embedding search → Document and chunk storage: stores and loads chunks (evidence: `MedAssist/app/retrieval.py`)
- Embedding search → Sentence Transformers: embeds text (evidence: `MedAssist/app/retrieval.py`)
- Embedding search → FAISS index: builds and searches (evidence: `MedAssist/app/retrieval.py`)
- Answer generation → Ollama service: requests completion (evidence: `MedAssist/app/llm.py`)
- User records → MySQL: queries and writes (evidence: `MedAssist/app/database.py`)
- Document and chunk storage → MySQL: queries and writes (evidence: `MedAssist/app/database.py`)
- RAG evaluation → Text chunking: tests chunking (evidence: `MedAssist/app/evaluate.py`)
- RAG evaluation → Embedding search: measures retrieval (evidence: `MedAssist/app/evaluate.py`)
- RAG evaluation → Answer generation: measures answers (evidence: `MedAssist/app/evaluate.py`)
