# rohankumar-1/brain-model architecture

> Architecture diagram of the GitHub repository rohankumar-1/brain-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohankumar-1/brain-model
- Repository: https://github.com/rohankumar-1/brain-model

## Overview

BrainQuery is a 3D brain CT/MRI foundation-model package whose main workflow turns raw cohort data into registered, indexed volumes, trains self-supervised and task-conditioned models, then evaluates them on held-out tasks and a versioned benchmark. Its other documented capabilities include few-shot task learning, frozen-encoder transfer, segmentation, and published-encoder comparisons. The graph emphasizes those domain stages and the shared encoder/data layers. Some subsystems are represented by their exact enclosing directories because their implementation was not sampled; edges reflect README statements or shown source references.

Main entry points: [`brain/prep/store.py`](https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/store.py) (Processed store), [`brain/data/volumes.py`](https://github.com/rohankumar-1/brain-model/blob/main/brain/data/volumes.py) (SSL volume data), [`brain/multitask/model.py`](https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/model.py) (BrainQuery model), [`brain/downstream`](https://github.com/rohankumar-1/brain-model/tree/main/brain/downstream) (Frozen transfer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Preprocessing"]
  node_download["Dataset fetch"]
  node_sources["Source readers<br/>[sources.py]"]
  node_prep_pipeline["Volume processing<br/>[pipeline.py]"]
  node_store[("Processed store<br/>[store.py]")]
  node_index["Volume index<br/>[index.py]"]
end

subgraph group_learn["Model training"]
  node_ssl_data["SSL volume data<br/>[volumes.py]"]
  node_ssl_trainer["LeJEPA training<br/>[lejepa3d.py]"]
  node_joint_trainer["Joint training<br/>[joint.py]"]
  node_training_engine["Training engine<br/>[engine.py]"]
end

subgraph group_tasks["Task learning"]
  node_task_registry["Task registry<br/>[registry.py]"]
  node_task_labels["Label building<br/>[labels.py]"]
  node_task_data["Task batches<br/>[data.py]"]
  node_brainquery["BrainQuery model<br/>[model.py]"]
  node_task_training["Multitask training<br/>[multitask.py]"]
  node_fewshot["Few-shot learning<br/>[fewshot.py]"]
end

subgraph group_eval["Evaluation"]
  node_downstream["Frozen transfer"]
  node_published["Published adapters"]
  node_benchmark["Benchmark suite"]
  node_test_eval["Head evaluation<br/>[evaluate.py]"]
  node_reports["Evaluation reports<br/>[report.py]"]
end

subgraph group_core["Shared core"]
  node_encoder["3D ViT encoder<br/>[vit3d.py]"]
  node_windowing["Intensity windowing<br/>[windowing.py]"]
end

node_user(("Researcher"))
node_cohorts[("Raw cohorts")]

node_user -->|"fetches data"| node_download
node_cohorts -->|"supplies archives"| node_download
node_download -->|"provides inputs"| node_sources
node_sources -->|"reads cases"| node_prep_pipeline
node_prep_pipeline -->|"writes volumes"| node_store
node_store -->|"indexes volumes"| node_index
node_index -->|"selects splits"| node_ssl_data
node_store -->|"loads volumes"| node_ssl_data
node_ssl_data -->|"provides crops"| node_ssl_trainer
node_ssl_trainer -->|"runs training"| node_training_engine
node_ssl_trainer -->|"trains encoder"| node_encoder
node_joint_trainer -->|"runs training"| node_training_engine
node_joint_trainer -->|"trains jointly"| node_encoder
node_task_registry -->|"defines tasks"| node_task_labels
node_task_labels -->|"supplies targets"| node_task_data
node_store -->|"loads scans"| node_task_data
node_task_data -->|"provides batches"| node_task_training
node_task_training -->|"trains model"| node_brainquery
node_brainquery -->|"uses encoder"| node_encoder
node_task_training -->|"runs training"| node_training_engine
node_user -->|"learns task"| node_fewshot
node_fewshot -->|"adapts model"| node_brainquery
node_user -->|"runs transfer"| node_downstream
node_downstream -->|"embeds scans"| node_encoder
node_published -->|"provides adapters"| node_downstream
node_user -->|"runs benchmark"| node_benchmark
node_benchmark -->|"evaluates encoders"| node_downstream
node_user -->|"scores heads"| node_test_eval
node_test_eval -->|"evaluates heads"| node_brainquery
node_benchmark -->|"summarizes results"| node_reports
node_windowing -->|"windows intensities"| node_ssl_data

click node_download "https://github.com/rohankumar-1/brain-model/tree/main/brain/datasets"
click node_sources "https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/sources.py"
click node_prep_pipeline "https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/pipeline.py"
click node_store "https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/store.py"
click node_index "https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/index.py"
click node_ssl_data "https://github.com/rohankumar-1/brain-model/blob/main/brain/data/volumes.py"
click node_ssl_trainer "https://github.com/rohankumar-1/brain-model/blob/main/brain/train/lejepa3d.py"
click node_joint_trainer "https://github.com/rohankumar-1/brain-model/blob/main/brain/train/joint.py"
click node_training_engine "https://github.com/rohankumar-1/brain-model/blob/main/brain/train/engine.py"
click node_encoder "https://github.com/rohankumar-1/brain-model/blob/main/brain/models/vit3d.py"
click node_windowing "https://github.com/rohankumar-1/brain-model/blob/main/brain/common/windowing.py"
click node_task_registry "https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/registry.py"
click node_task_labels "https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/labels.py"
click node_task_data "https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/data.py"
click node_brainquery "https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/model.py"
click node_task_training "https://github.com/rohankumar-1/brain-model/blob/main/brain/train/multitask.py"
click node_fewshot "https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/fewshot.py"
click node_downstream "https://github.com/rohankumar-1/brain-model/tree/main/brain/downstream"
click node_published "https://github.com/rohankumar-1/brain-model/tree/main/brain/downstream/adapters"
click node_benchmark "https://github.com/rohankumar-1/brain-model/tree/main/brain/bench"
click node_test_eval "https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/evaluate.py"
click node_reports "https://github.com/rohankumar-1/brain-model/blob/main/brain/eval/report.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_download,node_sources,node_prep_pipeline,node_store,node_index toneBlue
class node_ssl_data,node_ssl_trainer,node_joint_trainer,node_training_engine,node_cohorts toneAmber
class node_task_registry,node_task_labels,node_task_data,node_brainquery,node_task_training,node_fewshot toneMint
class node_downstream,node_published,node_benchmark,node_test_eval,node_reports toneRose
class node_encoder,node_windowing,node_user toneIndigo
```

## Components

### Preprocessing

- [Dataset fetch](https://github.com/rohankumar-1/brain-model/tree/main/brain/datasets): `brain/datasets`
- [Source readers](https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/sources.py): `brain/prep/sources.py`
- [Volume processing](https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/pipeline.py): `brain/prep/pipeline.py`
- [Processed store](https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/store.py): `brain/prep/store.py`
- [Volume index](https://github.com/rohankumar-1/brain-model/blob/main/brain/prep/index.py): `brain/prep/index.py`

### Model training

- [SSL volume data](https://github.com/rohankumar-1/brain-model/blob/main/brain/data/volumes.py): `brain/data/volumes.py`
- [LeJEPA training](https://github.com/rohankumar-1/brain-model/blob/main/brain/train/lejepa3d.py): `brain/train/lejepa3d.py`
- [Joint training](https://github.com/rohankumar-1/brain-model/blob/main/brain/train/joint.py): `brain/train/joint.py`
- [Training engine](https://github.com/rohankumar-1/brain-model/blob/main/brain/train/engine.py): `brain/train/engine.py`

### Task learning

- [Task registry](https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/registry.py): `brain/multitask/registry.py`
- [Label building](https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/labels.py): `brain/multitask/labels.py`
- [Task batches](https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/data.py): `brain/multitask/data.py`
- [BrainQuery model](https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/model.py): `brain/multitask/model.py`
- [Multitask training](https://github.com/rohankumar-1/brain-model/blob/main/brain/train/multitask.py): `brain/train/multitask.py`
- [Few-shot learning](https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/fewshot.py): `brain/multitask/fewshot.py`

### Evaluation

- [Frozen transfer](https://github.com/rohankumar-1/brain-model/tree/main/brain/downstream): `brain/downstream`
- [Published adapters](https://github.com/rohankumar-1/brain-model/tree/main/brain/downstream/adapters): `brain/downstream/adapters`
- [Benchmark suite](https://github.com/rohankumar-1/brain-model/tree/main/brain/bench): `brain/bench`
- [Head evaluation](https://github.com/rohankumar-1/brain-model/blob/main/brain/multitask/evaluate.py): `brain/multitask/evaluate.py`
- [Evaluation reports](https://github.com/rohankumar-1/brain-model/blob/main/brain/eval/report.py): `brain/eval/report.py`

### Shared core

- [3D ViT encoder](https://github.com/rohankumar-1/brain-model/blob/main/brain/models/vit3d.py): `brain/models/vit3d.py`
- [Intensity windowing](https://github.com/rohankumar-1/brain-model/blob/main/brain/common/windowing.py): `brain/common/windowing.py`

### Other components

- **Researcher**
- **Raw cohorts**

## Connections

- Researcher → Dataset fetch: fetches data (evidence: `README.md`)
- Raw cohorts → Dataset fetch: supplies archives (evidence: `README.md`)
- Dataset fetch → Source readers: provides inputs (evidence: `README.md`)
- Source readers → Volume processing: reads cases (evidence: `brain/prep/pipeline.py`)
- Volume processing → Processed store: writes volumes (evidence: `README.md`)
- Processed store → Volume index: indexes volumes (evidence: `brain/prep/index.py`)
- Volume index → SSL volume data: selects splits (evidence: `README.md`)
- Processed store → SSL volume data: loads volumes (evidence: `brain/data/volumes.py`)
- SSL volume data → LeJEPA training: provides crops (evidence: `README.md`)
- LeJEPA training → Training engine: runs training (evidence: `brain/train/engine.py`)
- LeJEPA training → 3D ViT encoder: trains encoder (evidence: `README.md`)
- Joint training → Training engine: runs training (evidence: `README.md`)
- Joint training → 3D ViT encoder: trains jointly (evidence: `README.md`)
- Task registry → Label building: defines tasks (evidence: `brain/multitask/labels.py`)
- Label building → Task batches: supplies targets (evidence: `README.md`)
- Processed store → Task batches: loads scans (evidence: `brain/multitask/data.py`)
- Task batches → Multitask training: provides batches (evidence: `README.md`)
- Multitask training → BrainQuery model: trains model (evidence: `brain/train/multitask.py`)
- BrainQuery model → 3D ViT encoder: uses encoder (evidence: `README.md`)
- Multitask training → Training engine: runs training (evidence: `brain/train/engine.py`)
- Researcher → Few-shot learning: learns task (evidence: `README.md`)
- Few-shot learning → BrainQuery model: adapts model (evidence: `brain/multitask/fewshot.py`)
- Researcher → Frozen transfer: runs transfer (evidence: `README.md`)
- Frozen transfer → 3D ViT encoder: embeds scans (evidence: `brain/downstream/embed3d.py`)
- Published adapters → Frozen transfer: provides adapters (evidence: `README.md`)
- Researcher → Benchmark suite: runs benchmark (evidence: `README.md`)
- Benchmark suite → Frozen transfer: evaluates encoders (evidence: `README.md`)
- Researcher → Head evaluation: scores heads (evidence: `README.md`)
- Head evaluation → BrainQuery model: evaluates heads (evidence: `README.md`)
- Benchmark suite → Evaluation reports: summarizes results (evidence: `README.md`)
- Intensity windowing → SSL volume data: windows intensities (evidence: `brain/data/volumes.py`)
