# izhanruaif/lung-cancer-subtype-classification architecture

> Architecture diagram of the GitHub repository izhanruaif/lung-cancer-subtype-classification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/izhanruaif/lung-cancer-subtype-classification
- Repository: https://github.com/izhanruaif/lung-cancer-subtype-classification

## Overview

This is an academic lung-CT subtype-classification decision-support platform, not a diagnostic device. A clinician signs in, manages a patient, uploads a scan, requests a prediction, reviews its subtype probabilities and Grad-CAM visualization, and accesses PDF reports and history. The graph separates the web interface, API/domain handlers, inference pipeline, and persistence. README workflow statements support the broad product stages; source-index references and excerpts support the implementation links. Several route and UI implementations were not excerpted, so their internals are not expanded.

Main entry points: [`frontend/src/App.tsx`](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/App.tsx) (Workspace and navigation), [`backend/app/main.py`](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/api/client.ts`](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/api/client.ts) (API client), [`backend/app/database/session.py`](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/database/session.py) (Database session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_app["Workspace and navigation<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_login["Sign-in page<br/>[LoginPage.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_patients_ui["Patient directory<br/>[PatientsPage.tsx]"]
  node_upload_ui["Scan upload<br/>[UploadPage.tsx]"]
  node_result_ui["Prediction results"]
  node_gradcam_ui["Heatmap viewer<br/>[GradCamViewer.tsx]"]
  node_reports_ui["Reports page<br/>[ReportsPage.tsx]"]
end

subgraph group_api["API and domain"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_patients_api["Patient management<br/>[patients.py]"]
  node_images_api["Image upload<br/>[images.py]"]
  node_predictions_api["Prediction endpoint<br/>[predictions.py]"]
  node_reports_api["Report endpoint<br/>[reports.py]"]
  node_security["Token security<br/>[security.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_ml["Inference and explanation"]
  node_ai_service["Inference service<br/>[ai_service.py]"]
  node_preprocess["CT preprocessing<br/>[dicom_loader.py]"]
  node_cnn["Attention CNN<br/>[attention_cnn.py]"]
  node_gradcam["Grad-CAM engine<br/>[gradcam.py]"]
end

subgraph group_storage["Persistence and reports"]
  node_db_session["Database session<br/>[session.py]"]
  node_records[("Patient and prediction records<br/>[models.py]")]
  node_pdf["PDF generation<br/>[pdf_service.py]"]
end

node_clinician(("Clinician"))

node_clinician -->|"uses"| node_app
node_app -->|"renders"| node_login
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_patients_ui
node_app -->|"renders"| node_upload_ui
node_app -->|"renders"| node_result_ui
node_app -->|"renders"| node_reports_ui
node_login -->|"authenticates via"| node_api_client
node_patients_ui -->|"requests data"| node_api_client
node_upload_ui -->|"uploads and predicts"| node_api_client
node_result_ui -->|"requests prediction"| node_api_client
node_result_ui -->|"renders"| node_gradcam_ui
node_reports_ui -.->|"loads reports"| node_api_client
node_dashboard -.->|"loads summary data"| node_api_client
node_api_client -->|"calls REST API"| node_api_entry
node_api_entry -->|"registers"| node_auth
node_api_entry -->|"registers"| node_patients_api
node_api_entry -->|"registers"| node_images_api
node_api_entry -->|"registers"| node_predictions_api
node_api_entry -->|"registers"| node_reports_api
node_api_entry -->|"creates tables with"| node_db_session
node_auth -->|"uses token functions"| node_security
node_auth -->|"queries user"| node_records
node_auth -->|"gets database session"| node_db_session
node_patients_api -->|"uses patient records"| node_records
node_patients_api -->|"gets database session"| node_db_session
node_images_api -->|"uses image records"| node_records
node_images_api -->|"gets database session"| node_db_session
node_predictions_api -->|"requests inference"| node_ai_service
node_predictions_api -->|"uses prediction records"| node_records
node_predictions_api -->|"gets database session"| node_db_session
node_reports_api -->|"generates PDF"| node_pdf
node_reports_api -->|"uses report records"| node_records
node_reports_api -->|"gets database session"| node_db_session
node_ai_service -->|"prepares input"| node_preprocess
node_ai_service -->|"runs inference"| node_cnn
node_ai_service -->|"generates heatmap"| node_gradcam
node_records -->|"uses declarative base"| node_db_session

click node_app "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/api/client.ts"
click node_login "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/LoginPage.tsx"
click node_dashboard "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_patients_ui "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/PatientsPage.tsx"
click node_upload_ui "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/UploadPage.tsx"
click node_result_ui "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/PredictionResultPage.tsx"
click node_gradcam_ui "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/components/GradCamViewer.tsx"
click node_reports_ui "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/ReportsPage.tsx"
click node_api_entry "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/main.py"
click node_auth "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/auth.py"
click node_patients_api "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/patients.py"
click node_images_api "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/images.py"
click node_predictions_api "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/predictions.py"
click node_reports_api "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/reports.py"
click node_security "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/core/security.py"
click node_schemas "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/schemas/schemas.py"
click node_ai_service "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/services/ai_service.py"
click node_preprocess "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/ml/preprocessing/dicom_loader.py"
click node_cnn "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/ml/models/attention_cnn.py"
click node_gradcam "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/ml/explainability/gradcam.py"
click node_db_session "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/database/session.py"
click node_records "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/models/models.py"
click node_pdf "https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/services/pdf_service.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_app,node_api_client,node_login,node_dashboard,node_patients_ui,node_upload_ui,node_result_ui,node_gradcam_ui,node_reports_ui toneBlue
class node_api_entry,node_auth,node_patients_api,node_images_api,node_predictions_api,node_reports_api,node_security,node_schemas toneAmber
class node_ai_service,node_preprocess,node_cnn,node_gradcam toneMint
class node_db_session,node_records,node_pdf toneRose
class node_clinician toneIndigo
```

## Components

### Web application

- [Workspace and navigation](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Sign-in page](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Dashboard](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Patient directory](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/PatientsPage.tsx): `frontend/src/pages/PatientsPage.tsx`
- [Scan upload](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/UploadPage.tsx): `frontend/src/pages/UploadPage.tsx`
- [Prediction results](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/PredictionResultPage.tsx): `frontend/src/pages/PredictionResultPage.tsx`
- [Heatmap viewer](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/components/GradCamViewer.tsx): `frontend/src/components/GradCamViewer.tsx`
- [Reports page](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/frontend/src/pages/ReportsPage.tsx): `frontend/src/pages/ReportsPage.tsx`

### API and domain

- [FastAPI application](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Patient management](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/patients.py): `backend/app/api/patients.py`
- [Image upload](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/images.py): `backend/app/api/images.py`
- [Prediction endpoint](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/predictions.py): `backend/app/api/predictions.py`
- [Report endpoint](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/api/reports.py): `backend/app/api/reports.py`
- [Token security](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [API schemas](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/schemas/schemas.py): `backend/app/schemas/schemas.py`

### Inference and explanation

- [Inference service](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [CT preprocessing](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/ml/preprocessing/dicom_loader.py): `ml/preprocessing/dicom_loader.py`
- [Attention CNN](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/ml/models/attention_cnn.py): `ml/models/attention_cnn.py`
- [Grad-CAM engine](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/ml/explainability/gradcam.py): `ml/explainability/gradcam.py`

### Persistence and reports

- [Database session](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [Patient and prediction records](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/models/models.py): `backend/app/models/models.py`
- [PDF generation](https://github.com/izhanruaif/lung-cancer-subtype-classification/blob/main/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`

### Other components

- **Clinician**

## Connections

- Clinician → Workspace and navigation: uses (evidence: `README.md`)
- Workspace and navigation → Sign-in page: renders (evidence: `frontend/src/App.tsx`)
- Workspace and navigation → Dashboard: renders (evidence: `frontend/src/App.tsx`)
- Workspace and navigation → Patient directory: renders (evidence: `frontend/src/App.tsx`)
- Workspace and navigation → Scan upload: renders (evidence: `frontend/src/App.tsx`)
- Workspace and navigation → Prediction results: renders (evidence: `frontend/src/App.tsx`)
- Workspace and navigation → Reports page: renders (evidence: `frontend/src/App.tsx`)
- Sign-in page → API client: authenticates via (evidence: `frontend/src/pages/LoginPage.tsx`)
- Patient directory → API client: requests data (evidence: `frontend/src/pages/PatientsPage.tsx`)
- Scan upload → API client: uploads and predicts (evidence: `frontend/src/pages/UploadPage.tsx`)
- Prediction results → API client: requests prediction (evidence: `frontend/src/pages/PredictionResultPage.tsx`)
- Prediction results → Heatmap viewer: renders (evidence: `frontend/src/pages/PredictionResultPage.tsx`)
- Reports page → API client: loads reports
- Dashboard → API client: loads summary data
- API client → FastAPI application: calls REST API (evidence: `README.md`)
- FastAPI application → Authentication: registers (evidence: `backend/app/main.py`)
- FastAPI application → Patient management: registers (evidence: `backend/app/main.py`)
- FastAPI application → Image upload: registers (evidence: `backend/app/main.py`)
- FastAPI application → Prediction endpoint: registers (evidence: `backend/app/main.py`)
- FastAPI application → Report endpoint: registers (evidence: `backend/app/main.py`)
- FastAPI application → Database session: creates tables with (evidence: `backend/app/main.py`)
- Authentication → Token security: uses token functions (evidence: `backend/app/api/auth.py`)
- Authentication → Patient and prediction records: queries user (evidence: `backend/app/api/auth.py`)
- Authentication → Database session: gets database session (evidence: `backend/app/api/auth.py`)
- Patient management → Patient and prediction records: uses patient records (evidence: `backend/app/api/patients.py`)
- Patient management → Database session: gets database session (evidence: `backend/app/api/patients.py`)
- Image upload → Patient and prediction records: uses image records (evidence: `backend/app/api/images.py`)
- Image upload → Database session: gets database session (evidence: `backend/app/api/images.py`)
- Prediction endpoint → Inference service: requests inference (evidence: `backend/app/api/predictions.py`)
- Prediction endpoint → Patient and prediction records: uses prediction records (evidence: `backend/app/api/predictions.py`)
- Prediction endpoint → Database session: gets database session (evidence: `backend/app/api/predictions.py`)
- Report endpoint → PDF generation: generates PDF (evidence: `backend/app/api/reports.py`)
- Report endpoint → Patient and prediction records: uses report records (evidence: `backend/app/api/reports.py`)
- Report endpoint → Database session: gets database session (evidence: `backend/app/api/reports.py`)
- Inference service → CT preprocessing: prepares input (evidence: `backend/app/services/ai_service.py`)
- Inference service → Attention CNN: runs inference (evidence: `backend/app/services/ai_service.py`)
- Inference service → Grad-CAM engine: generates heatmap (evidence: `backend/app/services/ai_service.py`)
- Patient and prediction records → Database session: uses declarative base (evidence: `backend/app/models/models.py`)
