# kadaak/neuro-vision architecture

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

- Interactive diagram: https://gitdiagram.com/kadaak/neuro-vision
- Repository: https://github.com/kadaak/neuro-vision

## Overview

NeuroVision AI is a brain-MRI workstation: users upload scans, request segmentation and quantitative analysis, view generated assets, and download reports. Its runtime separates API orchestration, imaging/analysis services, ML inference, persistence, and document generation; the repository also contains a distinct U-Net training pipeline. README-documented capabilities include NIfTI ingestion, the specialist/provider directory, and two report workflows. Some subsystem details are documented but their implementation was not sampled, so those relationships are identified from the README rather than inferred from filenames.

Main entry points: [`backend/api/analysis.py`](https://github.com/kadaak/neuro-vision/blob/main/backend/api/analysis.py) (Analysis API), [`ml/train.py`](https://github.com/kadaak/neuro-vision/blob/main/ml/train.py) (U-Net Training), [`frontend/js/app.js`](https://github.com/kadaak/neuro-vision/blob/main/frontend/js/app.js) (Medical Workstation), [`backend/api/reports.py`](https://github.com/kadaak/neuro-vision/blob/main/backend/api/reports.py) (Reports API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_workstation["Medical Workstation<br/>[app.js]"]
  node_upload_api["Upload API<br/>[upload.py]"]
  node_analysis_api["Analysis API<br/>[analysis.py]"]
  node_reports_api["Reports API<br/>[reports.py]"]
  node_backend_config["Backend Settings<br/>[config.py]"]
  node_provider_directory["Provider Directory<br/>[app.js]"]
end

subgraph group_analysis["Imaging Analysis"]
  node_image_service["Image Loading<br/>[image_service.py]"]
  node_preprocessing["Image Preprocessing<br/>[preprocessing.py]"]
  node_seg_service["Segmentation Orchestrator"]
  node_components["Lesion Components"]
  node_tumor_metrics["Tumor Morphometrics"]
  node_distance_service["Pairwise Distances"]
  node_visualization["Scan Visualization"]
  node_image_utils["Image Utilities<br/>[image_utils.py]"]
end

subgraph group_ml["ML Pipeline"]
  node_predictor["Model Predictor<br/>[predictor.py]"]
  node_unet["U-Net Model<br/>[unet.py]"]
  node_mock_seg["Fallback Segmentation<br/>[segmentation.py]"]
  node_ml_dataset["Training Dataset<br/>[dataset.py]"]
  node_ml_train["U-Net Training<br/>[train.py]"]
  node_ml_config["Training Settings<br/>[config.py]"]
  node_ml_losses["Training Losses<br/>[losses.py]"]
  node_ml_metrics["Training Metrics<br/>[metrics.py]"]
end

subgraph group_data["Study Data"]
  node_study_db[("Study Database<br/>[database.py]")]
  node_schemas["Validated Results<br/>[schemas.py]"]
end

subgraph group_reports["Clinical Reports"]
  node_report_service["Report Orchestrator<br/>[report_service.py]"]
  node_pdf_generator["AI PDF Report<br/>[pdf_generator.py]"]
  node_docx_generator["AI DOCX Report<br/>[docx_generator.py]"]
  node_doctor_report["Doctor PDF Report"]
end

node_user(("Clinical User"))

node_user -->|"uses"| node_workstation
node_workstation -->|"uploads scan"| node_upload_api
node_workstation -->|"requests analysis"| node_analysis_api
node_workstation -->|"requests report"| node_reports_api
node_upload_api -->|"uses settings"| node_backend_config
node_upload_api -->|"records study"| node_study_db
node_analysis_api -->|"loads and saves"| node_study_db
node_analysis_api -->|"loads scan"| node_image_service
node_analysis_api -->|"prepares image"| node_preprocessing
node_analysis_api -->|"requests mask"| node_seg_service
node_analysis_api -->|"detects lesions"| node_components
node_analysis_api -->|"generates assets"| node_visualization
node_analysis_api -->|"measures lesions"| node_tumor_metrics
node_analysis_api -->|"measures distances"| node_distance_service
node_analysis_api -->|"returns validated result"| node_schemas
node_visualization -->|"normalizes image"| node_image_utils
node_seg_service -->|"selects predictor"| node_predictor
node_predictor -->|"runs model"| node_unet
node_predictor -->|"uses fallback"| node_mock_seg
node_tumor_metrics -->|"builds tumor results"| node_schemas
node_distance_service -->|"builds distance results"| node_schemas
node_analysis_api -.->|"displays results"| node_provider_directory
node_ml_train -->|"loads paired data"| node_ml_dataset
node_ml_train -->|"trains model"| node_unet
node_ml_train -->|"computes loss"| node_ml_losses
node_ml_train -->|"evaluates model"| node_ml_metrics
node_ml_train -->|"uses settings"| node_ml_config
node_reports_api -->|"loads study"| node_study_db
node_reports_api -->|"requests generation"| node_report_service
node_report_service -->|"generates PDF"| node_pdf_generator
node_report_service -->|"generates DOCX"| node_docx_generator
node_reports_api -->|"generates clinical PDF"| node_doctor_report
node_doctor_report -.->|"provides care report"| node_user

click node_workstation "https://github.com/kadaak/neuro-vision/blob/main/frontend/js/app.js"
click node_upload_api "https://github.com/kadaak/neuro-vision/blob/main/backend/api/upload.py"
click node_analysis_api "https://github.com/kadaak/neuro-vision/blob/main/backend/api/analysis.py"
click node_reports_api "https://github.com/kadaak/neuro-vision/blob/main/backend/api/reports.py"
click node_backend_config "https://github.com/kadaak/neuro-vision/blob/main/backend/config.py"
click node_image_service "https://github.com/kadaak/neuro-vision/blob/main/backend/services/image_service.py"
click node_preprocessing "https://github.com/kadaak/neuro-vision/blob/main/processing/preprocessing.py"
click node_seg_service "https://github.com/kadaak/neuro-vision/blob/main/backend/services/segmentation_service.py"
click node_components "https://github.com/kadaak/neuro-vision/blob/main/processing/connected_components.py"
click node_tumor_metrics "https://github.com/kadaak/neuro-vision/blob/main/backend/services/tumor_analysis_service.py"
click node_distance_service "https://github.com/kadaak/neuro-vision/blob/main/backend/services/distance_service.py"
click node_visualization "https://github.com/kadaak/neuro-vision/blob/main/backend/services/visualization_service.py"
click node_image_utils "https://github.com/kadaak/neuro-vision/blob/main/backend/utils/image_utils.py"
click node_predictor "https://github.com/kadaak/neuro-vision/blob/main/ml/inference/predictor.py"
click node_unet "https://github.com/kadaak/neuro-vision/blob/main/ml/models/unet.py"
click node_mock_seg "https://github.com/kadaak/neuro-vision/blob/main/processing/segmentation.py"
click node_ml_dataset "https://github.com/kadaak/neuro-vision/blob/main/ml/dataset.py"
click node_ml_train "https://github.com/kadaak/neuro-vision/blob/main/ml/train.py"
click node_ml_config "https://github.com/kadaak/neuro-vision/blob/main/ml/config.py"
click node_ml_losses "https://github.com/kadaak/neuro-vision/blob/main/ml/losses.py"
click node_ml_metrics "https://github.com/kadaak/neuro-vision/blob/main/ml/metrics.py"
click node_study_db "https://github.com/kadaak/neuro-vision/blob/main/backend/models/database.py"
click node_schemas "https://github.com/kadaak/neuro-vision/blob/main/backend/models/schemas.py"
click node_report_service "https://github.com/kadaak/neuro-vision/blob/main/backend/services/report_service.py"
click node_pdf_generator "https://github.com/kadaak/neuro-vision/blob/main/reports/pdf_generator.py"
click node_docx_generator "https://github.com/kadaak/neuro-vision/blob/main/reports/docx_generator.py"
click node_doctor_report "https://github.com/kadaak/neuro-vision/blob/main/reports/doctor_report_generator.py"
click node_provider_directory "https://github.com/kadaak/neuro-vision/blob/main/frontend/js/app.js"

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_workstation,node_upload_api,node_analysis_api,node_reports_api,node_backend_config,node_provider_directory,node_user toneBlue
class node_image_service,node_preprocessing,node_seg_service,node_components,node_tumor_metrics,node_distance_service,node_visualization,node_image_utils toneAmber
class node_predictor,node_unet,node_mock_seg,node_ml_dataset,node_ml_train,node_ml_config,node_ml_losses,node_ml_metrics toneMint
class node_study_db,node_schemas toneRose
class node_report_service,node_pdf_generator,node_docx_generator,node_doctor_report toneIndigo
```

## Components

### API and UI

- [Medical Workstation](https://github.com/kadaak/neuro-vision/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [Upload API](https://github.com/kadaak/neuro-vision/blob/main/backend/api/upload.py): `backend/api/upload.py`
- [Analysis API](https://github.com/kadaak/neuro-vision/blob/main/backend/api/analysis.py): `backend/api/analysis.py`
- [Reports API](https://github.com/kadaak/neuro-vision/blob/main/backend/api/reports.py): `backend/api/reports.py`
- [Backend Settings](https://github.com/kadaak/neuro-vision/blob/main/backend/config.py): `backend/config.py`
- [Provider Directory](https://github.com/kadaak/neuro-vision/blob/main/frontend/js/app.js): `frontend/js/app.js`

### Imaging Analysis

- [Image Loading](https://github.com/kadaak/neuro-vision/blob/main/backend/services/image_service.py): `backend/services/image_service.py`
- [Image Preprocessing](https://github.com/kadaak/neuro-vision/blob/main/processing/preprocessing.py): `processing/preprocessing.py`
- [Segmentation Orchestrator](https://github.com/kadaak/neuro-vision/blob/main/backend/services/segmentation_service.py): `backend/services/segmentation_service.py`
- [Lesion Components](https://github.com/kadaak/neuro-vision/blob/main/processing/connected_components.py): `processing/connected_components.py`
- [Tumor Morphometrics](https://github.com/kadaak/neuro-vision/blob/main/backend/services/tumor_analysis_service.py): `backend/services/tumor_analysis_service.py`
- [Pairwise Distances](https://github.com/kadaak/neuro-vision/blob/main/backend/services/distance_service.py): `backend/services/distance_service.py`
- [Scan Visualization](https://github.com/kadaak/neuro-vision/blob/main/backend/services/visualization_service.py): `backend/services/visualization_service.py`
- [Image Utilities](https://github.com/kadaak/neuro-vision/blob/main/backend/utils/image_utils.py): `backend/utils/image_utils.py`

### ML Pipeline

- [Model Predictor](https://github.com/kadaak/neuro-vision/blob/main/ml/inference/predictor.py): `ml/inference/predictor.py`
- [U-Net Model](https://github.com/kadaak/neuro-vision/blob/main/ml/models/unet.py): `ml/models/unet.py`
- [Fallback Segmentation](https://github.com/kadaak/neuro-vision/blob/main/processing/segmentation.py): `processing/segmentation.py`
- [Training Dataset](https://github.com/kadaak/neuro-vision/blob/main/ml/dataset.py): `ml/dataset.py`
- [U-Net Training](https://github.com/kadaak/neuro-vision/blob/main/ml/train.py): `ml/train.py`
- [Training Settings](https://github.com/kadaak/neuro-vision/blob/main/ml/config.py): `ml/config.py`
- [Training Losses](https://github.com/kadaak/neuro-vision/blob/main/ml/losses.py): `ml/losses.py`
- [Training Metrics](https://github.com/kadaak/neuro-vision/blob/main/ml/metrics.py): `ml/metrics.py`

### Study Data

- [Study Database](https://github.com/kadaak/neuro-vision/blob/main/backend/models/database.py): `backend/models/database.py`
- [Validated Results](https://github.com/kadaak/neuro-vision/blob/main/backend/models/schemas.py): `backend/models/schemas.py`

### Clinical Reports

- [Report Orchestrator](https://github.com/kadaak/neuro-vision/blob/main/backend/services/report_service.py): `backend/services/report_service.py`
- [AI PDF Report](https://github.com/kadaak/neuro-vision/blob/main/reports/pdf_generator.py): `reports/pdf_generator.py`
- [AI DOCX Report](https://github.com/kadaak/neuro-vision/blob/main/reports/docx_generator.py): `reports/docx_generator.py`
- [Doctor PDF Report](https://github.com/kadaak/neuro-vision/blob/main/reports/doctor_report_generator.py): `reports/doctor_report_generator.py`

### Other components

- **Clinical User**

## Connections

- Clinical User → Medical Workstation: uses
- Medical Workstation → Upload API: uploads scan
- Medical Workstation → Analysis API: requests analysis
- Medical Workstation → Reports API: requests report
- Upload API → Backend Settings: uses settings (evidence: `backend/api/upload.py`)
- Upload API → Study Database: records study (evidence: `backend/api/upload.py`)
- Analysis API → Study Database: loads and saves (evidence: `backend/api/analysis.py`)
- Analysis API → Image Loading: loads scan (evidence: `backend/api/analysis.py`)
- Analysis API → Image Preprocessing: prepares image (evidence: `backend/api/analysis.py`)
- Analysis API → Segmentation Orchestrator: requests mask (evidence: `backend/api/analysis.py`)
- Analysis API → Lesion Components: detects lesions (evidence: `backend/api/analysis.py`)
- Analysis API → Scan Visualization: generates assets (evidence: `backend/api/analysis.py`)
- Analysis API → Tumor Morphometrics: measures lesions (evidence: `backend/api/analysis.py`)
- Analysis API → Pairwise Distances: measures distances (evidence: `backend/api/analysis.py`)
- Analysis API → Validated Results: returns validated result (evidence: `backend/api/analysis.py`)
- Scan Visualization → Image Utilities: normalizes image (evidence: `backend/services/visualization_service.py`)
- Segmentation Orchestrator → Model Predictor: selects predictor (evidence: `backend/services/segmentation_service.py`)
- Model Predictor → U-Net Model: runs model (evidence: `ml/inference/predictor.py`)
- Model Predictor → Fallback Segmentation: uses fallback (evidence: `ml/inference/predictor.py`)
- Tumor Morphometrics → Validated Results: builds tumor results (evidence: `backend/services/tumor_analysis_service.py`)
- Pairwise Distances → Validated Results: builds distance results (evidence: `backend/services/distance_service.py`)
- Analysis API → Provider Directory: displays results
- U-Net Training → Training Dataset: loads paired data (evidence: `ml/train.py`)
- U-Net Training → U-Net Model: trains model (evidence: `ml/train.py`)
- U-Net Training → Training Losses: computes loss (evidence: `ml/train.py`)
- U-Net Training → Training Metrics: evaluates model (evidence: `ml/train.py`)
- U-Net Training → Training Settings: uses settings (evidence: `ml/train.py`)
- Reports API → Study Database: loads study (evidence: `backend/api/reports.py`)
- Reports API → Report Orchestrator: requests generation (evidence: `backend/api/reports.py`)
- Report Orchestrator → AI PDF Report: generates PDF (evidence: `backend/services/report_service.py`)
- Report Orchestrator → AI DOCX Report: generates DOCX (evidence: `backend/services/report_service.py`)
- Reports API → Doctor PDF Report: generates clinical PDF (evidence: `backend/api/reports.py`)
- Doctor PDF Report → Clinical User: provides care report