# ucl/nextbrain architecture

> Architecture diagram of the GitHub repository ucl/nextbrain, 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/ucl/nextbrain
- Repository: https://github.com/ucl/nextbrain

## Overview

NextBrain is an interactive browser for correlating patient MRI projections with standard/high-resolution histology and labels. The main workflow starts in the atlas view: users select a patient or atlas location, navigate MRI or histology, and the application updates corresponding coordinates and images. Separate capabilities include MRI projection synchronization, block-to-histology mapping, image-channel and resolution controls, and label overlays. Source excerpts show the atlas orchestration and several image/coordinate calls; relationships for unsampled components are included only where the SOURCE INDEX or README supports them.

Main entry points: [`ui/src/components/atlas/atlasImages/AtlasImages.tsx`](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasImages/AtlasImages.tsx) (Atlas image coordinator), [`ui/src/components/atlas/atlasOptions/AtlasOptions.tsx`](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/AtlasOptions.tsx) (Atlas options), [`ui/src/pages/Atlas.tsx`](https://github.com/ucl/nextbrain/blob/development/ui/src/pages/Atlas.tsx) (Atlas page), [`ui/src/components/atlas/atlasOptions/AtlasNavigation.tsx`](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/AtlasNavigation.tsx) (Atlas navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_navigation["App navigation"]
  node_app["Application routes<br/>[App.tsx]"]
  node_home["Home<br/>[Home.tsx]"]
  node_atlas_page["Atlas page<br/>[Atlas.tsx]"]
end

subgraph group_atlas_ui["Atlas controls"]
  node_atlas_options["Atlas options<br/>[AtlasOptions.tsx]"]
  node_atlas_navigation["Atlas navigation"]
  node_patient_select["Patient selection<br/>[PatientSelect.tsx]"]
  node_image_controls["Image controls"]
  node_label_display["Label display<br/>[Label.tsx]"]
end

subgraph group_imaging["Imaging and coordinates"]
  node_atlas_images["Atlas image coordinator<br/>[AtlasImages.tsx]"]
  node_mri_images["MRI projections<br/>[MriImages.tsx]"]
  node_histology_images["Histology images"]
  node_image_children["Image layers"]
  node_scrollbars["Histology scrollbar<br/>[Scrollbars.tsx]"]
  node_mri_transform["MRI coordinate transforms"]
  node_histology_transform["Histology coordinate mapping"]
  node_matrix_access["Matrix access and math<br/>[getMatrix.ts]"]
  node_label_parser["Histology label lookup"]
  node_npz_parser["NPZ data parser<br/>[npzParser.ts]"]
  node_coord_models["Coordinate and image models"]
  node_block_finder["Block finder utility<br/>[block_finder.py]"]
end

subgraph group_support["Shared runtime"]
  node_shared_ui["Loading and errors<br/>[LoadingSpinner.tsx]"]
end

node_user(("Atlas user"))
node_asset_service[("Remote atlas assets")]

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_atlas_page
node_user -.->|"browses"| node_atlas_page
node_atlas_page -->|"renders"| node_atlas_images
node_atlas_page -->|"renders"| node_atlas_options
node_atlas_page -->|"fetches dimensions"| node_asset_service
node_atlas_options -->|"renders"| node_atlas_navigation
node_atlas_options -->|"renders"| node_patient_select
node_atlas_options -->|"renders"| node_image_controls
node_atlas_options -->|"renders"| node_label_display
node_atlas_navigation -->|"fetches ontology"| node_asset_service
node_atlas_navigation -->|"uses"| node_matrix_access
node_atlas_navigation -.->|"provides navigation coordinates"| node_atlas_images
node_atlas_images -->|"renders"| node_mri_images
node_atlas_images -->|"renders"| node_histology_images
node_atlas_images -->|"renders"| node_scrollbars
node_atlas_images -->|"calculates MRI coordinates"| node_mri_transform
node_atlas_images -->|"calculates histology coordinates"| node_histology_transform
node_atlas_images -->|"looks up labels"| node_label_parser
node_atlas_images -->|"loads matrices"| node_matrix_access
node_histology_images -->|"renders"| node_image_children
node_histology_images -->|"fetches image layers"| node_asset_service
node_histology_images -->|"sends click coordinates"| node_atlas_images
node_label_parser -->|"loads label arrays"| node_npz_parser
node_label_parser -->|"loads label data"| node_asset_service
node_matrix_access -->|"loads matrices"| node_asset_service
node_atlas_images -->|"shows loading and errors"| node_shared_ui
node_atlas_images -->|"uses coordinate state"| node_coord_models
node_mri_images -->|"uses MRI coordinates"| node_coord_models
node_scrollbars -->|"uses histology coordinates"| node_coord_models

click node_app "https://github.com/ucl/nextbrain/blob/development/ui/src/App.tsx"
click node_home "https://github.com/ucl/nextbrain/blob/development/ui/src/pages/Home.tsx"
click node_atlas_page "https://github.com/ucl/nextbrain/blob/development/ui/src/pages/Atlas.tsx"
click node_atlas_options "https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/AtlasOptions.tsx"
click node_atlas_navigation "https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/AtlasNavigation.tsx"
click node_patient_select "https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/PatientSelect.tsx"
click node_image_controls "https://github.com/ucl/nextbrain/tree/development/ui/src/components/atlas/atlasOptions"
click node_label_display "https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/Label.tsx"
click node_atlas_images "https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasImages/AtlasImages.tsx"
click node_mri_images "https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasImages/MriImages.tsx"
click node_histology_images "https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasImages/HistologyImages.tsx"
click node_image_children "https://github.com/ucl/nextbrain/tree/development/ui/src/components/atlas/atlasImages"
click node_scrollbars "https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/scrollbars/Scrollbars.tsx"
click node_mri_transform "https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/calculateMriImageCoords.ts"
click node_histology_transform "https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/calculateHistologyImageCoords.ts"
click node_matrix_access "https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/getMatrix.ts"
click node_label_parser "https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/histologyLabelParser.ts"
click node_npz_parser "https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/npzParser.ts"
click node_coord_models "https://github.com/ucl/nextbrain/tree/development/ui/src/models"
click node_block_finder "https://github.com/ucl/nextbrain/blob/development/src/block_finder.py"
click node_shared_ui "https://github.com/ucl/nextbrain/blob/development/ui/src/components/shared/LoadingSpinner.tsx"

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_home,node_atlas_page,node_user toneBlue
class node_atlas_options,node_atlas_navigation,node_patient_select,node_image_controls,node_label_display,node_asset_service toneAmber
class node_atlas_images,node_mri_images,node_histology_images,node_image_children,node_scrollbars,node_mri_transform,node_histology_transform,node_matrix_access,node_label_parser,node_npz_parser,node_coord_models,node_block_finder toneMint
class node_shared_ui toneRose
```

## Components

### App navigation

- [Application routes](https://github.com/ucl/nextbrain/blob/development/ui/src/App.tsx): `ui/src/App.tsx`
- [Home](https://github.com/ucl/nextbrain/blob/development/ui/src/pages/Home.tsx): `ui/src/pages/Home.tsx`
- [Atlas page](https://github.com/ucl/nextbrain/blob/development/ui/src/pages/Atlas.tsx): `ui/src/pages/Atlas.tsx`

### Atlas controls

- [Atlas options](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/AtlasOptions.tsx): `ui/src/components/atlas/atlasOptions/AtlasOptions.tsx`
- [Atlas navigation](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/AtlasNavigation.tsx): `ui/src/components/atlas/atlasOptions/AtlasNavigation.tsx`
- [Patient selection](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/PatientSelect.tsx): `ui/src/components/atlas/atlasOptions/PatientSelect.tsx`
- [Image controls](https://github.com/ucl/nextbrain/tree/development/ui/src/components/atlas/atlasOptions): `ui/src/components/atlas/atlasOptions`
- [Label display](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasOptions/Label.tsx): `ui/src/components/atlas/atlasOptions/Label.tsx`

### Imaging and coordinates

- [Atlas image coordinator](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasImages/AtlasImages.tsx): `ui/src/components/atlas/atlasImages/AtlasImages.tsx`
- [MRI projections](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasImages/MriImages.tsx): `ui/src/components/atlas/atlasImages/MriImages.tsx`
- [Histology images](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/atlasImages/HistologyImages.tsx): `ui/src/components/atlas/atlasImages/HistologyImages.tsx`
- [Image layers](https://github.com/ucl/nextbrain/tree/development/ui/src/components/atlas/atlasImages): `ui/src/components/atlas/atlasImages`
- [Histology scrollbar](https://github.com/ucl/nextbrain/blob/development/ui/src/components/atlas/scrollbars/Scrollbars.tsx): `ui/src/components/atlas/scrollbars/Scrollbars.tsx`
- [MRI coordinate transforms](https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/calculateMriImageCoords.ts): `ui/src/components/utils/calculateMriImageCoords.ts`
- [Histology coordinate mapping](https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/calculateHistologyImageCoords.ts): `ui/src/components/utils/calculateHistologyImageCoords.ts`
- [Matrix access and math](https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/getMatrix.ts): `ui/src/components/utils/getMatrix.ts`
- [Histology label lookup](https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/histologyLabelParser.ts): `ui/src/components/utils/histologyLabelParser.ts`
- [NPZ data parser](https://github.com/ucl/nextbrain/blob/development/ui/src/components/utils/npzParser.ts): `ui/src/components/utils/npzParser.ts`
- [Coordinate and image models](https://github.com/ucl/nextbrain/tree/development/ui/src/models): `ui/src/models`
- [Block finder utility](https://github.com/ucl/nextbrain/blob/development/src/block_finder.py): `src/block_finder.py`

### Shared runtime

- [Loading and errors](https://github.com/ucl/nextbrain/blob/development/ui/src/components/shared/LoadingSpinner.tsx): `ui/src/components/shared/LoadingSpinner.tsx`

### Other components

- **Atlas user**
- **Remote atlas assets**

## Connections

- Atlas user → Application routes: opens
- Application routes → Home: routes to (evidence: `ui/src/App.tsx`)
- Application routes → Atlas page: routes to (evidence: `ui/src/App.tsx`)
- Atlas user → Atlas page: browses
- Atlas page → Atlas image coordinator: renders (evidence: `ui/src/pages/Atlas.tsx`)
- Atlas page → Atlas options: renders (evidence: `ui/src/pages/Atlas.tsx`)
- Atlas page → Remote atlas assets: fetches dimensions (evidence: `ui/src/pages/Atlas.tsx`)
- Atlas options → Atlas navigation: renders (evidence: `ui/src/components/atlas/atlasOptions/AtlasOptions.tsx`)
- Atlas options → Patient selection: renders (evidence: `ui/src/components/atlas/atlasOptions/AtlasOptions.tsx`)
- Atlas options → Image controls: renders (evidence: `ui/src/components/atlas/atlasOptions/AtlasOptions.tsx`)
- Atlas options → Label display: renders (evidence: `ui/src/components/atlas/atlasOptions/AtlasOptions.tsx`)
- Atlas navigation → Remote atlas assets: fetches ontology (evidence: `ui/src/components/atlas/atlasOptions/AtlasNavigation.tsx`)
- Atlas navigation → Matrix access and math: uses (evidence: `ui/src/components/atlas/atlasOptions/AtlasNavigation.tsx`)
- Atlas navigation → Atlas image coordinator: provides navigation coordinates
- Atlas image coordinator → MRI projections: renders (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- Atlas image coordinator → Histology images: renders (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- Atlas image coordinator → Histology scrollbar: renders (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- Atlas image coordinator → MRI coordinate transforms: calculates MRI coordinates (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- Atlas image coordinator → Histology coordinate mapping: calculates histology coordinates (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- Atlas image coordinator → Histology label lookup: looks up labels (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- Atlas image coordinator → Matrix access and math: loads matrices (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- Histology images → Image layers: renders (evidence: `ui/src/components/atlas/atlasImages/HistologyImages.tsx`)
- Histology images → Remote atlas assets: fetches image layers (evidence: `ui/src/components/atlas/atlasImages/HistologyImages.tsx`)
- Histology images → Atlas image coordinator: sends click coordinates (evidence: `ui/src/components/atlas/atlasImages/HistologyImages.tsx`)
- Histology label lookup → NPZ data parser: loads label arrays (evidence: `ui/src/components/utils/histologyLabelParser.ts`)
- Histology label lookup → Remote atlas assets: loads label data (evidence: `ui/src/components/utils/histologyLabelParser.ts`)
- Matrix access and math → Remote atlas assets: loads matrices (evidence: `ui/src/components/utils/getMatrix.ts`)
- Atlas image coordinator → Loading and errors: shows loading and errors (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- Atlas image coordinator → Coordinate and image models: uses coordinate state (evidence: `ui/src/components/atlas/atlasImages/AtlasImages.tsx`)
- MRI projections → Coordinate and image models: uses MRI coordinates (evidence: `ui/src/components/atlas/atlasImages/MriImages.tsx`)
- Histology scrollbar → Coordinate and image models: uses histology coordinates (evidence: `ui/src/components/atlas/scrollbars/Scrollbars.tsx`)
