# alleninstitute/openscope_databook architecture

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

- Interactive diagram: https://gitdiagram.com/alleninstitute/openscope_databook
- Repository: https://github.com/alleninstitute/openscope_databook

## Overview

##### Project type and purpose
- This is a documentation‐centric static‐site project (“OpenScope Databook”) built with Jupyter Book/Sphinx. Its goal is to host reproducible neuroscience tutorials and analyses using Python notebooks, NWB files, and the DANDI archive. It’s not a conventional client/server web app but a source‐to‐static‐site pipeline with CI/CD and data‐analysis utilities.

##### File structure
- Top-level:
- docs/ – all the Jupyter notebooks and markdown chapters that form the book.
- databook_utils/ – Python library modules (NWB, DANDI utilities, author/version insertion).
- data/ – sample datasets, schemas, classifiers for offline analysis.
- .github/workflows/ – CI/CD definitions (test, build, deploy, codespell).
- Dockerfile, requirements.txt, runtime.txt, setup.py, apt.txt – environment and packaging.
- Key patterns: source notebooks + helper modules → static‐site build via Jupyter Book → deployment to GitHub Pages. Workflows automate testing of notebooks and code, then build & push the site.

##### README for additional insights
- The README describes chapters, content goals, external dependencies (NWB, DANDI), and links to the deployed site and DOI. It confirms the pipeline’s inputs (notebooks, configs) and outputs (hosted HTML). There is no runtime backend service beyond static hosting.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Code and Content
    subgraph "Source Repository" 
        direction TB
        docs["docs/ (Notebooks & Markdown)"]:::source
        config1["docs/_config.yml"]:::source
        config2["docs/_toc.yml"]:::source
        basics["docs/basics/"]:::source
        first["docs/first-order/"]:::source
        higher["docs/higher-order/"]:::source
        viz["docs/visualization/"]:::source
        projects["docs/projects/"]:::source
        utils["databook_utils/"]:::source
        data["data/ (Sample Data & Schemas)"]:::data
        env1["Dockerfile"]:::source
        env2["apt.txt"]:::source
        env3["requirements.txt & runtime.txt"]:::source
        env4["setup.py"]:::source
        hook["postBuild"]:::source
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline (GitHub Actions)" 
        direction TB
        test["Test & Lint\n(.github/workflows/test.yml\n.github/workflows/codespell.yml)"]:::process
        buildJob["Build Site\n(.github/workflows/build.yml)"]:::process
        deploy["Deploy to GitHub Pages\n(.github/workflows/deploy.yml)"]:::process
    end

    %% Build Environment
    docker["Docker Build Env\n(Python, Jupyter Book, Sphinx)"]:::build

    %% Static Site Output
    output["_build/html (Static HTML)"]:::build

    %% Hosting
    pages["GitHub Pages\n(alleninstitute.github.io/openscope_databook)"]:::host

    %% External Services
    subgraph "External Dependencies"
        direction TB
        dandi["DANDI Archive"]:::external
        nwb["NWB Ecosystem"]:::external
        zenodo["Zenodo DOI Metadata"]:::external
    end

    %% Relationships
    docs & config1 & config2 & basics & first & higher & viz & projects & utils & data & env1 & env2 & env3 & env4 & hook -->|"git push"| test
    test -->|"on success"| buildJob
    buildJob --> docker
    docker -->|"jupyter-book build"| output
    output --> deploy
    deploy --> pages
    basics & first & higher & viz & projects -->|"read content & utils"| docker
    utils -->|"import modules"| docker
    data -->|"provide sample data"| docker
    pages -->|"serves site; users click links to"| dandi
    pages -->|"serves site; users click links to"| zenodo
    docker -->|"uses schema & files from"| data
    docker -->|"publishes to"| pages
    pages -->|"references"| nwb

    %% Click Events
    click docs "https://github.com/alleninstitute/openscope_databook/tree/main/docs/"
    click config1 "https://github.com/alleninstitute/openscope_databook/blob/main/docs/_config.yml"
    click config2 "https://github.com/alleninstitute/openscope_databook/blob/main/docs/_toc.yml"
    click basics "https://github.com/alleninstitute/openscope_databook/tree/main/docs/basics/"
    click first "https://github.com/alleninstitute/openscope_databook/tree/main/docs/first-order/"
    click higher "https://github.com/alleninstitute/openscope_databook/tree/main/docs/higher-order/"
    click viz "https://github.com/alleninstitute/openscope_databook/tree/main/docs/visualization/"
    click projects "https://github.com/alleninstitute/openscope_databook/tree/main/docs/projects/"
    click utils "https://github.com/alleninstitute/openscope_databook/tree/main/databook_utils/"
    click data "https://github.com/alleninstitute/openscope_databook/tree/main/data/"
    click test "https://github.com/alleninstitute/openscope_databook/blob/main/.github/workflows/test.yml"
    click test "https://github.com/alleninstitute/openscope_databook/blob/main/.github/workflows/codespell.yml"
    click buildJob "https://github.com/alleninstitute/openscope_databook/blob/main/.github/workflows/build.yml"
    click deploy "https://github.com/alleninstitute/openscope_databook/blob/main/.github/workflows/deploy.yml"
    click env1 "https://github.com/alleninstitute/openscope_databook/tree/main/Dockerfile"
    click env2 "https://github.com/alleninstitute/openscope_databook/blob/main/apt.txt"
    click env3 "https://github.com/alleninstitute/openscope_databook/blob/main/requirements.txt"
    click env3 "https://github.com/alleninstitute/openscope_databook/blob/main/runtime.txt"
    click env4 "https://github.com/alleninstitute/openscope_databook/blob/main/setup.py"
    click hook "https://github.com/alleninstitute/openscope_databook/tree/main/postBuild"

    %% Styles
    classDef source fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef data fill:#e6f2ff,stroke:#66b2ff,color:#000,stroke-dasharray: 5 5;
    classDef process fill:#d4edda,stroke:#28a745,color:#000;
    classDef build fill:#fff3cd,stroke:#ffcd39,color:#000;
    classDef host fill:#ffe5cc,stroke:#ff8c1a,color:#000;
    classDef external fill:#e5ccff,stroke:#b266ff,color:#000;
```
