# kabiththananparan/meditimeline-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kabiththananparan/meditimeline-ai
- Repository: https://github.com/kabiththananparan/meditimeline-ai

## Overview

#### Purpose and current entry point
MediTimeline AI is intended to ingest medical-record documents and build structured patient timelines for prescription, allergy, lab-trend, and clinical-reasoning analysis. The implemented repository is currently backend-focused; no React frontend, SQLite, ChromaDB, Groq integration, or dashboard source is present in the tree.

The FastAPI application entry point is `backend/app/main.py`. Upload handling begins at `backend/app/api/upload.py`.

#### API boundary and upload contract
`backend/app/api/upload.py` defines the HTTP-facing upload route(s), separating client file submission from document-processing logic. Request/response models are centralized in `backend/app/schemas/upload_schema.py`, providing the contract boundary between API consumers and internal services.

Flow: client uploads a document → API validates/normalizes through schema and route logic → service layer receives the file for processing.

#### Upload orchestration
`backend/app/services/upload_service.py` is the application service coordinating uploaded-file handling. It forms the primary control-flow boundary between transport concerns in `api/` and document extraction in `services/pdf_parser.py`.

This layer is the natural future integration point for persistence, patient/document identifiers, asynchronous jobs, and downstream timeline/analysis stages described in the README.

#### PDF extraction stage
`backend/app/services/pdf_parser.py` is the document-ingestion/extraction component. It converts uploaded PDF content into text or parsed material usable by later structured extraction.

The implemented pipeline therefore currently reaches: Upload → file handling → PDF parsing. The README’s later stages—AI structured extraction, timeline generation, interaction checking, lab analysis, and clinical reasoning—are product-intended stages but do not have corresponding source modules in this tree.

#### Application runtime and cross-cutting configuration
The backend uses Python/FastAPI, with runtime dependencies declared in `backend/requirements.txt`. Application bootstrap is located at `backend/app/main.py`.

Cross-cutting settings and logging are isolated from business services:
- `backend/app/core/config.py`
- `backend/app/core/logging.py`

These modules are the expected boundaries for environment-provided settings (such as future Groq credentials, storage locations, and database URLs) and operational observability.

#### Data and external-service posture
Sample/source medical-record organization exists under `data/DataSet YGC26/`, grouped by patient and year, for example:
- `data/DataSet YGC26/Patient x/Year 1`
- `data/DataSet YGC26/Patient y/Year 3`

The README names Groq, SQLite, and ChromaDB as planned platform dependencies, but the visible code tree contains no adapters, migrations, vector-store clients, or LLM client modules. Treat them as intended infrastructure rather than implemented runtime dependencies.

#### Key architectural gap
The repository has a clean initial layering—API → schema/service → parser—with configuration and logging outside the request pipeline. To realize the stated product architecture, add explicit bounded components after parsing: normalized medical-record extraction, durable patient/document storage, timeline assembly, medication/allergy/lab analysis, and a reasoning/query API. Keep these behind service interfaces rather than embedding clinical or AI logic in `backend/app/api/upload.py`.

Main entry points: [`backend/app/main.py`](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/main.py) (FastAPI bootstrap), [`backend/app/api/upload.py`](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/api/upload.py) (Upload routes), [`backend/app/services/pdf_parser.py`](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/services/pdf_parser.py) (PDF parser), [`backend/app/core/config.py`](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/core/config.py) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Backend Runtime"]
  node_main{{"FastAPI bootstrap<br/>application entry<br/>[main.py]"}}
  node_config["Settings<br/>configuration<br/>[config.py]"]
  node_logging["Logging<br/>observability<br/>[logging.py]"]
  node_requirements["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]
end

subgraph group_ingestion["Implemented Ingestion"]
  node_upload_api["Upload routes<br/>HTTP API<br/>[upload.py]"]
  node_upload_schema["Upload contract<br/>request/response schemas<br/>[upload_schema.py]"]
  node_upload_service["Upload orchestration<br/>application service<br/>[upload_service.py]"]
  node_pdf_parser["PDF parser<br/>document extraction<br/>[pdf_parser.py]"]
end

subgraph group_future["Planned Clinical Pipeline"]
  node_record_extraction["Normalized record extraction<br/>planned service"]
  node_timeline["Timeline assembly<br/>planned service"]
  node_clinical_analysis["Medication, allergy &amp; lab analysis<br/>planned analysis service"]
  node_reasoning_api["Reasoning/query API<br/>planned API service"]
end

subgraph group_data["Data Sources &amp; Storage"]
  node_dataset[("Medical-record dataset<br/>sample source documents")]
  node_patient_storage[("Patient/document storage<br/>planned durable store")]
end

node_client(("API client<br/>external client"))

node_client -->|"HTTP requests"| node_main
node_main -->|"registers"| node_upload_api
node_requirements -->|"runtime dependencies"| node_main
node_config -->|"settings"| node_main
node_logging -->|"observability"| node_main
node_upload_api -->|"validates contract"| node_upload_schema
node_upload_api -->|"submits file"| node_upload_service
node_upload_service -->|"extracts PDF content"| node_pdf_parser
node_dataset -.->|"representative PDFs"| node_pdf_parser
node_pdf_parser -.->|"parsed material"| node_record_extraction
node_record_extraction -.->|"persist records"| node_patient_storage
node_patient_storage -.->|"patient records"| node_timeline
node_timeline -.->|"timeline context"| node_clinical_analysis
node_clinical_analysis -.->|"findings"| node_reasoning_api
node_reasoning_api -.->|"queries and results"| node_client
node_config -.->|"future storage settings"| node_patient_storage

click node_main "https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/main.py"
click node_upload_api "https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/api/upload.py"
click node_upload_schema "https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/schemas/upload_schema.py"
click node_upload_service "https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/services/upload_service.py"
click node_pdf_parser "https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/services/pdf_parser.py"
click node_config "https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/core/config.py"
click node_logging "https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/core/logging.py"
click node_requirements "https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/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_main,node_config,node_logging,node_requirements toneBlue
class node_upload_api,node_upload_schema,node_upload_service,node_pdf_parser toneAmber
class node_record_extraction,node_timeline,node_clinical_analysis,node_reasoning_api toneMint
class node_dataset,node_patient_storage toneRose
class node_client toneNeutral
```

## Components

### Backend Runtime

- [FastAPI bootstrap](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/main.py): application entry · `backend/app/main.py`
- [Settings](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/core/config.py): configuration · Environment boundary for credentials, storage, and database settings. · `backend/app/core/config.py`
- [Logging](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/core/logging.py): observability · `backend/app/core/logging.py`
- [Python dependencies](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/requirements.txt): dependency manifest · `backend/requirements.txt`

### Implemented Ingestion

- [Upload routes](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/api/upload.py): HTTP API · `backend/app/api/upload.py`
- [Upload contract](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/schemas/upload_schema.py): request/response schemas · Defines the API boundary for upload payloads and responses. · `backend/app/schemas/upload_schema.py`
- [Upload orchestration](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/services/upload_service.py): application service · Coordinates file handling between transport and extraction. · `backend/app/services/upload_service.py`
- [PDF parser](https://github.com/kabiththananparan/meditimeline-ai/blob/main/backend/app/services/pdf_parser.py): document extraction · Converts uploaded PDF content into usable parsed text or material. · `backend/app/services/pdf_parser.py`

### Planned Clinical Pipeline

Product-intended stages not yet implemented.

- **Normalized record extraction**: planned service · Transforms parsed material into structured medical records.
- **Timeline assembly**: planned service · Builds chronological patient timelines from structured records.
- **Medication, allergy & lab analysis**: planned analysis service · Supports interaction checks and lab-trend analysis.
- **Reasoning/query API**: planned API service · Exposes clinical reasoning and timeline queries.

### Data Sources & Storage

- **Medical-record dataset**: sample source documents · Patient and year-organized medical-record files.
- **Patient/document storage**: planned durable store · Persists patient identities, source documents, and normalized records.

### Other components

- **API client**: external client

## Connections

- API client → FastAPI bootstrap: HTTP requests
- FastAPI bootstrap → Upload routes: registers
- Python dependencies → FastAPI bootstrap: runtime dependencies
- Settings → FastAPI bootstrap: settings
- Logging → FastAPI bootstrap: observability
- Upload routes → Upload contract: validates contract
- Upload routes → Upload orchestration: submits file
- Upload orchestration → PDF parser: extracts PDF content
- Medical-record dataset → PDF parser: representative PDFs
- PDF parser → Normalized record extraction: parsed material
- Normalized record extraction → Patient/document storage: persist records
- Patient/document storage → Timeline assembly: patient records
- Timeline assembly → Medication, allergy & lab analysis: timeline context
- Medication, allergy & lab analysis → Reasoning/query API: findings
- Reasoning/query API → API client: queries and results
- Settings → Patient/document storage: future storage settings