# kritanuscodingdelight/neuroscan-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kritanuscodingdelight/neuroscan-ai
- Repository: https://github.com/kritanuscodingdelight/neuroscan-ai

## Overview

NeuroScan AI is a web application that classifies structural brain MRI scans into four Alzheimer’s impairment stages and presents confidence, clinical guidance, and visual explanations. The primary workflow is scan upload, image preprocessing, model inference, then result and interpretation display; users can also access informational pages and API health/statistics capabilities. The graph reflects both the documented web and API surfaces. Some route internals and frontend wiring are unsampled, so uncertain connections are omitted.

Main entry points: [`backend/api.py`](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/api.py) (Prediction API), [`frontend/templates`](https://github.com/kritanuscodingdelight/neuroscan-ai/tree/main/frontend/templates) (Upload and results UI), [`frontend/static/js/script.js`](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/frontend/static/js/script.js) (Upload interactions), [`backend/utils/model_loader.py`](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/model_loader.py) (Model loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["Upload and results UI"]
  node_browser_js["Upload interactions<br/>[script.js]"]
  node_web_app["Web routes<br/>[app.py]"]
  node_api["Prediction API<br/>[api.py]"]
  node_result_cache["Result cache<br/>[api.py]"]
  node_results_ui["Analysis presentation<br/>[script.js]"]
  node_info_pages["Clinical information pages"]
end

subgraph group_inference["Classification pipeline"]
  node_preprocessor["MRI preprocessing<br/>[preprocessor.py]"]
  node_model_loader["Model loading<br/>[model_loader.py]"]
end

subgraph group_interpretation["Clinical interpretation"]
  node_gradcam["Grad-CAM++<br/>[grad_cam.py]"]
  node_explainer["Saliency explanations<br/>[explainer.py]"]
  node_clinical["Risk and recommendations<br/>[api.py]"]
end

subgraph group_integration["Model integration"]
  node_weights["Model checkpoint"]
  node_downloader["Model downloader"]
  node_class_names["Class mappings<br/>[class_names.json]"]
end

node_user(("Scan submitter"))
node_huggingface(("Hugging Face Hub"))

node_user -->|"submits scan"| node_frontend
node_frontend -->|"handles upload"| node_browser_js
node_browser_js -->|"requests prediction"| node_api
node_api -->|"preprocesses scan"| node_preprocessor
node_api -->|"loads model"| node_model_loader
node_model_loader -->|"loads checkpoint"| node_weights
node_api -->|"reads mappings"| node_class_names
node_downloader -.->|"downloads weights"| node_huggingface
node_api -->|"generates heatmap"| node_gradcam
node_api -->|"assesses prediction"| node_clinical
node_api -->|"stores result"| node_result_cache
node_browser_js -->|"renders response"| node_results_ui
node_api -->|"returns analysis"| node_results_ui
node_user -->|"views guidance"| node_info_pages
node_frontend -->|"requests web pages"| node_web_app

click node_frontend "https://github.com/kritanuscodingdelight/neuroscan-ai/tree/main/frontend/templates"
click node_browser_js "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/frontend/static/js/script.js"
click node_web_app "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/app.py"
click node_api "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/api.py"
click node_preprocessor "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/preprocessor.py"
click node_model_loader "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/model_loader.py"
click node_weights "https://github.com/kritanuscodingdelight/neuroscan-ai/tree/main/backend/models"
click node_downloader "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/model_downloader.py"
click node_class_names "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/models/class_names.json"
click node_result_cache "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/api.py"
click node_gradcam "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/grad_cam.py"
click node_explainer "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/explainer.py"
click node_clinical "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/api.py"
click node_results_ui "https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/frontend/static/js/script.js"
click node_info_pages "https://github.com/kritanuscodingdelight/neuroscan-ai/tree/main/frontend/templates"

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_frontend,node_browser_js,node_web_app,node_api,node_result_cache,node_results_ui,node_info_pages toneBlue
class node_preprocessor,node_model_loader toneAmber
class node_gradcam,node_explainer,node_clinical toneMint
class node_weights,node_downloader,node_class_names toneRose
class node_user,node_huggingface toneIndigo
```

## Components

### Web experience

- [Upload and results UI](https://github.com/kritanuscodingdelight/neuroscan-ai/tree/main/frontend/templates): `frontend/templates`
- [Upload interactions](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/frontend/static/js/script.js): `frontend/static/js/script.js`
- [Web routes](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/app.py): `backend/app.py`
- [Prediction API](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/api.py): `backend/api.py`
- [Result cache](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/api.py): `backend/api.py`
- [Analysis presentation](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/frontend/static/js/script.js): `frontend/static/js/script.js`
- [Clinical information pages](https://github.com/kritanuscodingdelight/neuroscan-ai/tree/main/frontend/templates): `frontend/templates`

### Classification pipeline

- [MRI preprocessing](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/preprocessor.py): `backend/utils/preprocessor.py`
- [Model loading](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/model_loader.py): `backend/utils/model_loader.py`

### Clinical interpretation

- [Grad-CAM++](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/grad_cam.py): `backend/utils/grad_cam.py`
- [Saliency explanations](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/explainer.py): `backend/utils/explainer.py`
- [Risk and recommendations](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/api.py): `backend/api.py`

### Model integration

- [Model checkpoint](https://github.com/kritanuscodingdelight/neuroscan-ai/tree/main/backend/models): `backend/models`
- [Model downloader](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/utils/model_downloader.py): `backend/utils/model_downloader.py`
- [Class mappings](https://github.com/kritanuscodingdelight/neuroscan-ai/blob/main/backend/models/class_names.json): `backend/models/class_names.json`

### Other components

- **Scan submitter**
- **Hugging Face Hub**

## Connections

- Scan submitter → Upload and results UI: submits scan
- Upload and results UI → Upload interactions: handles upload
- Upload interactions → Prediction API: requests prediction
- Prediction API → MRI preprocessing: preprocesses scan
- Prediction API → Model loading: loads model
- Model loading → Model checkpoint: loads checkpoint
- Prediction API → Class mappings: reads mappings
- Model downloader → Hugging Face Hub: downloads weights
- Prediction API → Grad-CAM++: generates heatmap
- Prediction API → Risk and recommendations: assesses prediction
- Prediction API → Result cache: stores result
- Upload interactions → Analysis presentation: renders response
- Prediction API → Analysis presentation: returns analysis
- Scan submitter → Clinical information pages: views guidance
- Upload and results UI → Web routes: requests web pages