# brainglobe/brainglobe-atlasapi architecture

> Architecture diagram of the GitHub repository brainglobe/brainglobe-atlasapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainglobe/brainglobe-atlasapi
- Repository: https://github.com/brainglobe/brainglobe-atlasapi

## Overview

##### Main components
- CLI Layer
– brainglobe_atlasapi/cli.py (entry point for console commands)
– list_atlases.py, show_atlases, update_atlases
- Core API Layer
– bg_atlas.py (BrainGlobeAtlas class)
– core.py, descriptors.py, config.py, utils.py, structure_class.py, structure_tree_util.py
- Atlas Generation Pipeline
– brainglobe_atlasapi/atlas_generation package
- atlas_scripts (per-atlas packaging scripts)
- annotation_utils.py, mesh_utils.py, metadata_utils.py, volume_utils.py, stacks.py, validate_atlases.py, wrapup.py
- pre_packaging subfolder (special preprocessing steps)
- Data & Storage
– Local cache directory (~/.brainglobe/<atlas_name>_vX.X) containing
- reference images (.npy or nifti)
- annotation images
- meshes (.obj)
- metadata (CSV, JSON)
– External remote repositories (e.g. Allen SDK, S3 or HTTP endpoints)
- Testing & QA
– tests/ (pytest suites covering atlasapi and atlas_generation)
– CI workflows (.github/workflows/test_and_deploy.yml)
– pre-commit, black, isort, codecov
- Documentation & Examples
– README.md, tutorials/Atlas API usage.ipynb

##### Relationships and interactions
- User → CLI Layer (command‐line “brainglobe-atlasapi”)
→ CLI Layer calls Core API functions (show_atlases, update_atlases)
→ Core API uses config and utilities to fetch, cache, and serve atlas data
- User → Python API (import BrainGlobeAtlas)
→ Core API factory returns Atlas object
→ Atlas object lazily loads reference, annotation, hemispheres, mesh, metadata
- Core API ↔ Local Data Cache (read/write files)
- Core API ↔ External Data Sources (download raw atlas data)
- Atlas Generation Pipeline (offline use by developers)
→ atlas_scripts read raw data from public URLs
→ pipeline utilities (annotation_utils, mesh_utils, etc.) process volumes & meshes
→ wrapup packages outputs into standard folder structure
- Testing harness exercises both API and pipeline modules

##### Architectural patterns & design principles
- Layered architecture: Presentation (CLI/tutorials), Domain (Core API), Infrastructure (data I/O), Pipeline (atlas generation)
- Modular plugin-style extensibility: each atlas has its own script in atlas_generation/atlas_scripts
- Separation of concerns: parsing, mesh creation, volume operations, metadata handling each in dedicated utility modules
- Lazy loading and caching: Atlas objects only load data on access

##### Call out key technologies & frameworks
- Python 3.8+
- PyPI packaging (pyproject.toml, MANIFEST.in)
- pytest for tests
- GitHub Actions for CI/CD
- pre-commit hooks (black, isort)
- External libs: numpy, nibabel, allensdk (optional), pandas

##### Final checklist
- Separation of at least these zones: User Interfaces, Core API, Atlas Generation Pipeline, Data Storage, External Services, Testing/CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        direction TB
        User["User"]:::external
        CLI_Main["CLI Layer\nbrainglobe_atlasapi/cli.py"]:::presentation
        CLI_List["list_atlases"]:::presentation
        CLI_Update["update_atlases"]:::presentation
        Python_API["Python API\n(import BrainGlobeAtlas)"]:::presentation
    end

    %% Core API Layer
    subgraph "Core API Layer"
        direction TB
        BG_Atlas["BrainGlobeAtlas\n(bg_atlas.py)"]:::core
        Core_Mod["core.py"]:::core
        Config["config.py"]:::core
        Descriptors["descriptors.py"]:::core
        Utils["utils.py"]:::core
        Struct_Class["structure_class.py"]:::core
        Struct_Tree["structure_tree_util.py"]:::core
    end

    %% Atlas Generation Pipeline
    subgraph "Atlas Generation Pipeline"
        direction TB
        AG_Packaging["wrapup.py"]:::pipeline
        AG_Validate["validate_atlases.py"]:::pipeline
        AG_Volume["volume_utils.py"]:::pipeline
        AG_Annotation["annotation_utils.py"]:::pipeline
        AG_Mesh["mesh_utils.py"]:::pipeline
        AG_Metadata["metadata_utils.py"]:::pipeline
        AG_Stacks["stacks.py"]:::pipeline
        subgraph "atlas_scripts (plugin extension)"
            direction TB
            AG_Scripts["atlas_generation/atlas_scripts/"]:::pipeline
            AG_Pre["pre_packaging"]:::pipeline
        end
    end

    %% Data & Storage
    subgraph "Data & Storage"
        direction TB
        Local_Cache[(Local Cache)]:::storage
        External_Svc[("External Data Sources\nHTTP/S3")]:::external
    end

    %% Testing & CI
    subgraph "Testing & QA"
        direction TB
        Tests["tests/"]:::test
        CI_Workflow[".github/workflows/test_and_deploy.yml"]:::test
        PreCommit[".pre-commit-config.yaml"]:::test
        Codecov[".codecov.yml"]:::test
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        direction TB
        README["README.md"]:::doc
        Tutorial["tutorials/Atlas API usage.ipynb"]:::doc
    end

    %% Connections
    User -->|"runs command"| CLI_Main
    CLI_Main -->|"list atlases"| CLI_List
    CLI_Main -->|"update atlases"| CLI_Update
    CLI_Main -->|"calls API"| BG_Atlas

    User -->|"imports API"| Python_API
    Python_API -->|"factory returns"| BG_Atlas

    BG_Atlas -->|"uses core functions"| Core_Mod
    Core_Mod --> Config
    Core_Mod --> Descriptors
    Core_Mod --> Utils
    Core_Mod --> Struct_Class
    Core_Mod --> Struct_Tree

    BG_Atlas -->|"reads/writes"| Local_Cache
    BG_Atlas -->|"downloads data"| External_Svc

    AG_Scripts -->|"use raw URLs"| External_Svc
    AG_Scripts --> AG_Annotation
    AG_Scripts --> AG_Volume
    AG_Scripts --> AG_Mesh
    AG_Scripts --> AG_Metadata
    AG_Scripts --> AG_Stacks
    AG_Annotation --> AG_Packaging
    AG_Volume --> AG_Packaging
    AG_Mesh --> AG_Packaging
    AG_Metadata --> AG_Packaging
    AG_Stacks --> AG_Packaging
    AG_Validate --> AG_Packaging

    Tests --> BG_Atlas
    Tests --> Core_Mod
    Tests --> AG_Scripts
    CI_Workflow --> Tests
    PreCommit --> Core_Mod
    Codecov --> Tests

    Tutorial --> Python_API
    README --> CLI_Main

    %% Click Events
    click CLI_Main "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/cli.py"
    click CLI_List "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/list_atlases.py"
    click CLI_Update "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/update_atlases.py"
    click BG_Atlas "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/bg_atlas.py"
    click Core_Mod "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/core.py"
    click Config "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/config.py"
    click Descriptors "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/descriptors.py"
    click Utils "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/utils.py"
    click Struct_Class "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/structure_class.py"
    click Struct_Tree "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/structure_tree_util.py"
    click AG_Packaging "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/atlas_generation/wrapup.py"
    click AG_Validate "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/atlas_generation/validate_atlases.py"
    click AG_Volume "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/atlas_generation/volume_utils.py"
    click AG_Annotation "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/atlas_generation/annotation_utils.py"
    click AG_Mesh "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/atlas_generation/mesh_utils.py"
    click AG_Metadata "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/atlas_generation/metadata_utils.py"
    click AG_Stacks "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/brainglobe_atlasapi/atlas_generation/stacks.py"
    click AG_Scripts "https://github.com/brainglobe/brainglobe-atlasapi/tree/main/brainglobe_atlasapi/atlas_generation/atlas_scripts/"
    click AG_Pre "https://github.com/brainglobe/brainglobe-atlasapi/tree/main/brainglobe_atlasapi/atlas_generation/atlas_scripts/pre_packaging/"
    click Tests "https://github.com/brainglobe/brainglobe-atlasapi/tree/main/tests/"
    click CI_Workflow "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/.github/workflows/test_and_deploy.yml"
    click PreCommit "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/.pre-commit-config.yaml"
    click Codecov "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/.codecov.yml"
    click README "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/README.md"
    click Tutorial "https://github.com/brainglobe/brainglobe-atlasapi/blob/main/tutorials/Atlas API usage.ipynb"

    %% Styles
    classDef presentation fill:#add8e6,stroke:#333,stroke-width:1px
    classDef core fill:#90ee90,stroke:#333,stroke-width:1px
    classDef pipeline fill:#ffa500,stroke:#333,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef external fill:#ffff99,stroke:#333,stroke-width:1px
    classDef test fill:#ffb6c1,stroke:#333,stroke-width:1px
    classDef doc fill:#dda0dd,stroke:#333,stroke-width:1px
```
