# arpitjain-coder/medical-report-simplification architecture

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

- Interactive diagram: https://gitdiagram.com/arpitjain-coder/medical-report-simplification
- Repository: https://github.com/arpitjain-coder/medical-report-simplification

## Overview

ReportSamjho AI helps users upload medical reports and review extracted results, risk assessments, simplified explanations, translations, and report-specific chat. The tree shows a Next.js frontend, a Node/Express backend, and a FastAPI ML service; the README describes the backend as a proxy. The clearest evidenced processing flow is in the ML service, which orchestrates seven stages. The repository also contains a separate Express API and a database schema. Some frontend-to-service wiring and backend behavior are not shown in the excerpts, so those links are omitted or marked unverified.

Main entry points: [`ml/main.py`](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/main.py) (ML API orchestrator), [`frontend/app`](https://github.com/arpitjain-coder/medical-report-simplification/tree/main/frontend/app) (Next.js application), [`backend/artifacts/api-server/src/routes`](https://github.com/arpitjain-coder/medical-report-simplification/tree/main/backend/artifacts/api-server/src/routes) (API routes), [`backend/artifacts/api-server/src/routes/auth.ts`](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/artifacts/api-server/src/routes/auth.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Next.js application"]
  node_upload["Report upload<br/>[page.tsx]"]
  node_report_views["Report views"]
  node_chat_ui["Chat panel<br/>[chat-panel.tsx]"]
  node_localization["Localization<br/>[i18n.ts]"]
end

subgraph group_services["Backend services"]
  node_backend_proxy["Node proxy<br/>[server.ts]"]
  node_express_app["Express API<br/>[app.ts]"]
  node_api_routes["API routes"]
  node_auth_routes["Authentication<br/>[auth.ts]"]
  node_pipeline["Report pipeline<br/>[pipeline.ts]"]
end

subgraph group_processing["Report processing"]
  node_ml_api["ML API orchestrator<br/>[main.py]"]
  node_ocr["OCR extraction<br/>[stage1_ocr.py]"]
  node_ner["Clinical entity extraction<br/>[stage2_ner.py]"]
  node_risk["Risk scoring"]
  node_rag["RAG and retrieval<br/>[stage4_rag.py]"]
  node_simplification["Result simplification"]
  node_translation["Translation"]
  node_chatbot["Report chatbot<br/>[stage7_chatbot.py]"]
  node_ml_extras["Clinical extras<br/>[ml_components.py]"]
end

subgraph group_data["Report data"]
  node_report_store[("Report database<br/>[reports.ts]")]
end

node_patient(("Patient"))
node_translation_service["Translation service"]

node_patient -.->|"uses"| node_webapp
node_webapp -.->|"offers upload"| node_upload
node_webapp -.->|"shows reports"| node_report_views
node_webapp -.->|"offers chat"| node_chat_ui
node_webapp -->|"uses translations"| node_localization
node_backend_proxy -.->|"proxies requests"| node_ml_api
node_express_app -->|"mounts routes"| node_api_routes
node_api_routes -->|"registers routes"| node_auth_routes
node_auth_routes -->|"reads and writes"| node_report_store
node_pipeline -->|"updates reports"| node_report_store
node_ml_api -->|"calls OCR"| node_ocr
node_ml_api -->|"calls NER"| node_ner
node_ml_api -->|"scores results"| node_risk
node_ml_api -->|"builds index"| node_rag
node_ml_api -->|"simplifies results"| node_simplification
node_ml_api -.->|"translates separately"| node_translation
node_ml_api -->|"answers questions"| node_chatbot
node_ml_api -->|"checks health"| node_translation_service

click node_webapp "https://github.com/arpitjain-coder/medical-report-simplification/tree/main/frontend/app"
click node_upload "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/frontend/app/(dashboard)/dashboard/upload/page.tsx"
click node_report_views "https://github.com/arpitjain-coder/medical-report-simplification/tree/main/frontend/app/(dashboard)/dashboard/reports"
click node_chat_ui "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/frontend/components/chat-panel.tsx"
click node_localization "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/frontend/lib/i18n.ts"
click node_backend_proxy "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/server.ts"
click node_express_app "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/artifacts/api-server/src/app.ts"
click node_api_routes "https://github.com/arpitjain-coder/medical-report-simplification/tree/main/backend/artifacts/api-server/src/routes"
click node_auth_routes "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/artifacts/api-server/src/routes/auth.ts"
click node_pipeline "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/artifacts/api-server/src/lib/pipeline.ts"
click node_ml_api "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/main.py"
click node_ocr "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage1_ocr.py"
click node_ner "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage2_ner.py"
click node_risk "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage3_risk_scoring.py"
click node_rag "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage4_rag.py"
click node_simplification "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage5_simplification.py"
click node_translation "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage6_translation.py"
click node_chatbot "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage7_chatbot.py"
click node_ml_extras "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/ml_components.py"
click node_report_store "https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/lib/db/src/schema/reports.ts"

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_webapp,node_upload,node_report_views,node_chat_ui,node_localization toneBlue
class node_backend_proxy,node_express_app,node_api_routes,node_auth_routes,node_pipeline toneAmber
class node_ml_api,node_ocr,node_ner,node_risk,node_rag,node_simplification,node_translation,node_chatbot,node_ml_extras toneMint
class node_report_store toneRose
class node_patient,node_translation_service toneIndigo
```

## Components

### Web experience

- [Next.js application](https://github.com/arpitjain-coder/medical-report-simplification/tree/main/frontend/app): `frontend/app`
- [Report upload](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/frontend/app/(dashboard)/dashboard/upload/page.tsx): `frontend/app/(dashboard)/dashboard/upload/page.tsx`
- [Report views](https://github.com/arpitjain-coder/medical-report-simplification/tree/main/frontend/app/(dashboard)/dashboard/reports): `frontend/app/(dashboard)/dashboard/reports`
- [Chat panel](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/frontend/components/chat-panel.tsx): `frontend/components/chat-panel.tsx`
- [Localization](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/frontend/lib/i18n.ts): `frontend/lib/i18n.ts`

### Backend services

- [Node proxy](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/server.ts): `backend/server.ts`
- [Express API](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/artifacts/api-server/src/app.ts): `backend/artifacts/api-server/src/app.ts`
- [API routes](https://github.com/arpitjain-coder/medical-report-simplification/tree/main/backend/artifacts/api-server/src/routes): `backend/artifacts/api-server/src/routes`
- [Authentication](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/artifacts/api-server/src/routes/auth.ts): `backend/artifacts/api-server/src/routes/auth.ts`
- [Report pipeline](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/artifacts/api-server/src/lib/pipeline.ts): `backend/artifacts/api-server/src/lib/pipeline.ts`

### Report processing

- [ML API orchestrator](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/main.py): `ml/main.py`
- [OCR extraction](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage1_ocr.py): `ml/stage1_ocr.py`
- [Clinical entity extraction](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage2_ner.py): `ml/stage2_ner.py`
- [Risk scoring](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage3_risk_scoring.py): `ml/stage3_risk_scoring.py`
- [RAG and retrieval](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage4_rag.py): `ml/stage4_rag.py`
- [Result simplification](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage5_simplification.py): `ml/stage5_simplification.py`
- [Translation](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage6_translation.py): `ml/stage6_translation.py`
- [Report chatbot](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/stage7_chatbot.py): `ml/stage7_chatbot.py`
- [Clinical extras](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/ml/ml_components.py): `ml/ml_components.py`

### Report data

- [Report database](https://github.com/arpitjain-coder/medical-report-simplification/blob/main/backend/lib/db/src/schema/reports.ts): `backend/lib/db/src/schema/reports.ts`

### Other components

- **Patient**
- **Translation service**

## Connections

- Patient → Next.js application: uses
- Next.js application → Report upload: offers upload
- Next.js application → Report views: shows reports
- Next.js application → Chat panel: offers chat
- Next.js application → Localization: uses translations
- Node proxy → ML API orchestrator: proxies requests
- Express API → API routes: mounts routes (evidence: `backend/artifacts/api-server/src/app.ts`)
- API routes → Authentication: registers routes (evidence: `backend/artifacts/api-server/src/routes/index.ts`)
- Authentication → Report database: reads and writes (evidence: `backend/artifacts/api-server/src/routes/auth.ts`)
- Report pipeline → Report database: updates reports (evidence: `backend/artifacts/api-server/src/lib/pipeline.ts`)
- ML API orchestrator → OCR extraction: calls OCR (evidence: `ml/main.py`)
- ML API orchestrator → Clinical entity extraction: calls NER (evidence: `ml/main.py`)
- ML API orchestrator → Risk scoring: scores results (evidence: `ml/main.py`)
- ML API orchestrator → RAG and retrieval: builds index (evidence: `ml/main.py`)
- ML API orchestrator → Result simplification: simplifies results (evidence: `ml/main.py`)
- ML API orchestrator → Translation: translates separately (evidence: `ml/main.py`)
- ML API orchestrator → Report chatbot: answers questions (evidence: `ml/main.py`)
- ML API orchestrator → Translation service: checks health (evidence: `ml/main.py`)
