# ultralytics/notebooks architecture

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

- Interactive diagram: https://gitdiagram.com/ultralytics/notebooks
- Repository: https://github.com/ultralytics/notebooks

## Overview

##### Project type and purpose
- This is an “example‐and‐documentation” repository. It provides a set of Jupyter notebooks showcasing Ultralytics YOLO workflows, plus tools for generating and formatting documentation tables in the README. There is no monolithic “application” here—rather a content library, CI pipelines, and helper scripts for docs.

##### File structure
- Top level:
- .github/workflows – CI pipelines (formatting, table generation)
- docs – configuration data (notebooks-data.yml) and a Python script (update-readme-table.py)
- notebooks – dozens of .ipynb example notebooks
- pyproject.toml – Python project metadata & dependencies
- README.md – landing page with table of notebooks
- External integrations: Google Colab, Kaggle, SageMaker badges embedded in README per notebook; links to YouTube, Ultralytics HUB, blogs, arXiv, etc.

##### README for additional insights
- The README is auto-generated by docs/update-readme-table.py reading docs/notebooks-data.yml.
- CI workflow table.yml runs on push to regenerate the table.
- format.yml enforces code & markdown formatting, probably via black/isort/pre-commit.

##### Elements
- Clear labels: “notebooks/”, “docs/”, “.github/workflows/”, “README.md”, “pyproject.toml”, external services
- docs/notebooks-data.yml → update-readme-table.py → README.md
- Push → GitHub Actions workflows → formatting & docs generation
- README badges → launch notebooks on Colab / Kaggle / SageMaker
- Blue rectangles for static content (notebooks, YAML)
- Green rectangles for scripts (update-readme-table.py)
- Orange rectangles for CI workflows
- Gray clouds for external services

##### Detailed capture of essential elements
- Dual CI workflows side by side, each pointing to the files they act on, and to the README as their output.
- External integrations as end‐user entry points triggered by badges in the README.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Developer["Developer"]:::external
    GitHubRepo["GitHub Repo (Source of Truth)"]:::repo

    subgraph Content
        Notebooks["notebooks/"]:::static
        DocsYAML["docs/notebooks-data.yml"]:::static
        PyProject["pyproject.toml"]:::static
    end

    subgraph Scripts
        UpdateScript["update-readme-table.py"]:::script
    end

    subgraph CI
        FormatWF["format.yml"]:::ci
        TableWF["table.yml"]:::ci
    end

    subgraph External
        Colab["Google Colab"]:::external
        Kaggle["Kaggle"]:::external
        SageMaker["SageMaker"]:::external
        Hub["Ultralytics Hub"]:::external
        YouTube["YouTube"]:::external
        Blogs["Blogs/arXiv"]:::external
    end

    Developer -->|edits content| GitHubRepo
    GitHubRepo -->|provides notebooks| Notebooks
    GitHubRepo -->|provides metadata| DocsYAML
    GitHubRepo -->|provides config| PyProject
    GitHubRepo -->|provides script| UpdateScript

    GitHubRepo -->|push triggers| FormatWF
    GitHubRepo -->|push triggers| TableWF

    FormatWF -->|formats code & notebooks| GitHubRepo
    TableWF -->|runs script on YAML| UpdateScript
    TableWF -->|generates| README

    README["README.md"]:::static
    TableWF --> README

    README --> Colab
    README --> Kaggle
    README --> SageMaker
    README --> Hub
    README --> YouTube
    README --> Blogs

    click GitHubRepo "https://github.com/ultralytics/notebooks/tree/main//"
    click Notebooks "https://github.com/ultralytics/notebooks/tree/main/notebooks/"
    click DocsYAML "https://github.com/ultralytics/notebooks/blob/main/docs/notebooks-data.yml"
    click UpdateScript "https://github.com/ultralytics/notebooks/blob/main/docs/update-readme-table.py"
    click FormatWF "https://github.com/ultralytics/notebooks/blob/main/.github/workflows/format.yml"
    click TableWF "https://github.com/ultralytics/notebooks/blob/main/.github/workflows/table.yml"
    click PyProject "https://github.com/ultralytics/notebooks/blob/main/pyproject.toml"
    click README "https://github.com/ultralytics/notebooks/blob/main/README.md"

    classDef static fill:#cfe2f3,stroke:#0366d6,stroke-width:1px
    classDef script fill:#d9ead3,stroke:#6aa84f,stroke-width:1px
    classDef ci fill:#f9cb9c,stroke:#e69138,stroke-width:1px
    classDef external fill:#d9d2e9,stroke:#6d9eeb,stroke-width:1px
    classDef repo fill:#a4c2f4,stroke:#1155cc,stroke-width:1px
```
