# rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation architecture

> Architecture diagram of the GitHub repository rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation
- Repository: https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation

## Overview

NeuroSeg combines a research framework for 3D BraTS tumor segmentation with a clinical-style dashboard for upload, inference, review, and model adaptation. The documented research workflow trains UNETR variants with masked self-distillation objectives and evaluates volumetric predictions; the dashboard adds human annotation and candidate-model management. Edges reflect sampled calls, imports, or README-described behavior; unsampled frontend-to-API wiring is not asserted.

Main entry points: [`dashboard/backend/app/api/adaptive_routes.py`](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/api/adaptive_routes.py) (Review Routes), [`src/models/unetr_baseline.py`](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/models/unetr_baseline.py) (UNETR Models), [`dashboard/frontend/src/App.jsx`](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/App.jsx) (Dashboard Shell), [`dashboard/backend/app/api/routes.py`](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/api/routes.py) (REST Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Segmentation Dashboard"]
  node_app["Dashboard Shell<br/>[App.jsx]"]
  node_upload["MRI Upload<br/>[UploadPage.jsx]"]
  node_viewer["3D Viewer<br/>[ViewerPage.jsx]"]
  node_adaptive_ui["Adaptive Dashboard"]
end

subgraph group_backend["Inference and Review"]
  node_api["REST Routes<br/>[routes.py]"]
  node_adaptive_api["Review Routes<br/>[adaptive_routes.py]"]
  node_server["FastAPI App<br/>[main.py]"]
  node_inference["Volume Inference"]
  node_volume["Volume and Slices<br/>[volume_service.py]"]
  node_tumor["Tumor Burden"]
  node_annotations["Voxel Annotations"]
  node_dataset["Training Dataset<br/>[dataset_service.py]"]
  node_training_service["Fine-Tuning Jobs"]
  node_registry[("Model Registry")]
  node_adaptive_schema["Workflow Schemas<br/>[adaptive.py]"]
end

subgraph group_research["Research Framework"]
  node_train_entry["Experiment CLI<br/>[main.py]"]
  node_adaptive_train["Adaptive Training<br/>[train_adaptive.py]"]
  node_brats_data["BraTS Data<br/>[brats_dataset.py]"]
  node_unetr["UNETR Models<br/>[unetr_baseline.py]"]
  node_masking["Patch Masking<br/>[masking.py]"]
  node_distill["Distillation Losses"]
  node_dense["Dense Predictor<br/>[dense_predictor.py]"]
  node_trainer["Training Loop<br/>[trainer.py]"]
  node_evaluation["Model Evaluation<br/>[evaluator.py]"]
  node_classify["Image Classifier<br/>[model.py]"]
end

subgraph group_voice["Voice Controls"]
  node_voice_parser["Voice Parser"]
  node_voice_commands["Command Registry<br/>[commandRegistry.js]"]
  node_voice_context["Voice Context<br/>[VoiceContext.jsx]"]
end

node_user(("Clinician / Researcher"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_upload
node_app -->|"renders"| node_viewer
node_app -->|"renders"| node_adaptive_ui
node_server -->|"registers"| node_api
node_server -->|"registers"| node_adaptive_api
node_server -->|"initializes"| node_inference
node_api -->|"runs"| node_inference
node_api -->|"queries"| node_volume
node_api -->|"queries"| node_tumor
node_adaptive_api -->|"edits and reviews"| node_annotations
node_adaptive_api -->|"starts jobs"| node_training_service
node_adaptive_api -->|"reads registry"| node_registry
node_adaptive_api -->|"validates requests"| node_adaptive_schema
node_train_entry -->|"dispatches training"| node_adaptive_train
node_brats_data -.->|"feeds model"| node_unetr
node_masking -.->|"masks student input"| node_unetr
node_unetr -.->|"provides tokens"| node_distill
node_unetr -.->|"provides tokens"| node_dense
node_trainer -.->|"applies masks"| node_masking
node_trainer -.->|"optimizes loss"| node_distill
node_trainer -.->|"optimizes loss"| node_dense
node_evaluation -->|"evaluates"| node_unetr
node_voice_context -.->|"provides controls"| node_voice_parser
node_voice_parser -->|"resolves commands"| node_voice_commands
node_user -->|"speaks commands"| node_voice_context

click node_app "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/App.jsx"
click node_upload "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/pages/UploadPage.jsx"
click node_viewer "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/pages/ViewerPage.jsx"
click node_adaptive_ui "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/pages/AdaptiveDashboardPage.jsx"
click node_api "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/api/routes.py"
click node_adaptive_api "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/api/adaptive_routes.py"
click node_server "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/main.py"
click node_inference "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/inference_service.py"
click node_volume "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/volume_service.py"
click node_tumor "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/tumor_burden_service.py"
click node_annotations "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/annotation_service.py"
click node_dataset "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/dataset_service.py"
click node_training_service "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/training_service.py"
click node_registry "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/model_registry_service.py"
click node_adaptive_schema "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/schemas/adaptive.py"
click node_train_entry "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/main.py"
click node_adaptive_train "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/scripts/train_adaptive.py"
click node_brats_data "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/data/brats_dataset.py"
click node_unetr "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/models/unetr_baseline.py"
click node_masking "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/training/masking.py"
click node_distill "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/losses/online_tokenizer.py"
click node_dense "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/models/dense_predictor.py"
click node_trainer "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/training/trainer.py"
click node_evaluation "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/evaluation/evaluator.py"
click node_classify "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/classifier/model.py"
click node_voice_parser "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/services/voiceCommandParser.js"
click node_voice_commands "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/services/commandRegistry.js"
click node_voice_context "https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/voice/VoiceContext.jsx"

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_upload,node_viewer,node_adaptive_ui toneBlue
class node_api,node_adaptive_api,node_server,node_inference,node_volume,node_tumor,node_annotations,node_dataset,node_training_service,node_registry,node_adaptive_schema toneAmber
class node_train_entry,node_adaptive_train,node_brats_data,node_unetr,node_masking,node_distill,node_dense,node_trainer,node_evaluation,node_classify toneMint
class node_voice_parser,node_voice_commands,node_voice_context toneRose
class node_user toneIndigo
```

## Components

### Segmentation Dashboard

- [Dashboard Shell](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/App.jsx): `dashboard/frontend/src/App.jsx`
- [MRI Upload](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/pages/UploadPage.jsx): `dashboard/frontend/src/pages/UploadPage.jsx`
- [3D Viewer](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/pages/ViewerPage.jsx): `dashboard/frontend/src/pages/ViewerPage.jsx`
- [Adaptive Dashboard](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/pages/AdaptiveDashboardPage.jsx): `dashboard/frontend/src/pages/AdaptiveDashboardPage.jsx`

### Inference and Review

- [REST Routes](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/api/routes.py): `dashboard/backend/app/api/routes.py`
- [Review Routes](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/api/adaptive_routes.py): `dashboard/backend/app/api/adaptive_routes.py`
- [FastAPI App](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/main.py): `dashboard/backend/app/main.py`
- [Volume Inference](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/inference_service.py): `dashboard/backend/app/services/inference_service.py`
- [Volume and Slices](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/volume_service.py): `dashboard/backend/app/services/volume_service.py`
- [Tumor Burden](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/tumor_burden_service.py): `dashboard/backend/app/services/tumor_burden_service.py`
- [Voxel Annotations](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/annotation_service.py): `dashboard/backend/app/services/annotation_service.py`
- [Training Dataset](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/dataset_service.py): `dashboard/backend/app/services/dataset_service.py`
- [Fine-Tuning Jobs](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/training_service.py): `dashboard/backend/app/services/training_service.py`
- [Model Registry](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/services/model_registry_service.py): `dashboard/backend/app/services/model_registry_service.py`
- [Workflow Schemas](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/backend/app/schemas/adaptive.py): `dashboard/backend/app/schemas/adaptive.py`

### Research Framework

- [Experiment CLI](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/main.py): `main.py`
- [Adaptive Training](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/scripts/train_adaptive.py): `scripts/train_adaptive.py`
- [BraTS Data](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/data/brats_dataset.py): `src/data/brats_dataset.py`
- [UNETR Models](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/models/unetr_baseline.py): `src/models/unetr_baseline.py`
- [Patch Masking](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/training/masking.py): `src/training/masking.py`
- [Distillation Losses](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/losses/online_tokenizer.py): `src/losses/online_tokenizer.py`
- [Dense Predictor](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/models/dense_predictor.py): `src/models/dense_predictor.py`
- [Training Loop](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/training/trainer.py): `src/training/trainer.py`
- [Model Evaluation](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/evaluation/evaluator.py): `src/evaluation/evaluator.py`
- [Image Classifier](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/src/classifier/model.py): `src/classifier/model.py`

### Voice Controls

- [Voice Parser](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/services/voiceCommandParser.js): `dashboard/frontend/src/services/voiceCommandParser.js`
- [Command Registry](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/services/commandRegistry.js): `dashboard/frontend/src/services/commandRegistry.js`
- [Voice Context](https://github.com/rahulnag-v/adaptive-self-distillation-3d-brain-tumor-segmentation/blob/main/dashboard/frontend/src/voice/VoiceContext.jsx): `dashboard/frontend/src/voice/VoiceContext.jsx`

### Other components

- **Clinician / Researcher**

## Connections

- Clinician / Researcher → Dashboard Shell: uses
- Dashboard Shell → MRI Upload: renders (evidence: `dashboard/frontend/src/App.jsx`)
- Dashboard Shell → 3D Viewer: renders (evidence: `dashboard/frontend/src/App.jsx`)
- Dashboard Shell → Adaptive Dashboard: renders (evidence: `dashboard/frontend/src/App.jsx`)
- FastAPI App → REST Routes: registers (evidence: `dashboard/backend/app/main.py`)
- FastAPI App → Review Routes: registers (evidence: `dashboard/backend/app/main.py`)
- FastAPI App → Volume Inference: initializes (evidence: `dashboard/backend/app/main.py`)
- REST Routes → Volume Inference: runs (evidence: `dashboard/backend/app/api/routes.py`)
- REST Routes → Volume and Slices: queries (evidence: `dashboard/backend/app/api/routes.py`)
- REST Routes → Tumor Burden: queries (evidence: `dashboard/backend/app/api/routes.py`)
- Review Routes → Voxel Annotations: edits and reviews (evidence: `dashboard/backend/app/api/adaptive_routes.py`)
- Review Routes → Fine-Tuning Jobs: starts jobs (evidence: `dashboard/backend/app/api/adaptive_routes.py`)
- Review Routes → Model Registry: reads registry (evidence: `dashboard/backend/app/api/adaptive_routes.py`)
- Review Routes → Workflow Schemas: validates requests (evidence: `dashboard/backend/app/api/adaptive_routes.py`)
- Experiment CLI → Adaptive Training: dispatches training (evidence: `main.py`)
- BraTS Data → UNETR Models: feeds model
- Patch Masking → UNETR Models: masks student input
- UNETR Models → Distillation Losses: provides tokens
- UNETR Models → Dense Predictor: provides tokens
- Training Loop → Patch Masking: applies masks
- Training Loop → Distillation Losses: optimizes loss
- Training Loop → Dense Predictor: optimizes loss
- Model Evaluation → UNETR Models: evaluates (evidence: `src/evaluation/evaluator.py`)
- Voice Context → Voice Parser: provides controls
- Voice Parser → Command Registry: resolves commands (evidence: `dashboard/frontend/src/services/voiceCommandParser.js`)
- Clinician / Researcher → Voice Context: speaks commands
