# jupyter/docker-stacks architecture

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

- Interactive diagram: https://gitdiagram.com/jupyter/docker-stacks
- Repository: https://github.com/jupyter/docker-stacks

## Overview

##### Project type and purpose
- This is an open-source tool (“Jupyter Docker Stacks”) whose primary responsibility is to produce, tag, test, document, and publish a family of Docker images bundling Jupyter applications (Lab, Notebook) and language-specific stacks (Python, R, Julia, Spark, etc.).
- The README and file tree confirm that the core use cases are:
- Building and publishing multi-flavor Docker images to Quay.io
- Tagging and manifest generation for reproducible image versions
- Automated testing of each image’s behavior
- Generating documentation (ReadTheDocs) and examples (Compose, OCP, Binder).

##### File structure
- Top-level “.github/workflows” & “.github/actions”: Continuous Integration and custom GitHub Actions definitions.
- “images/…-notebook”: one directory per image flavor, each containing a Dockerfile, helpers, and health checks.
- “tagging/”: Python library and CLI apps that compute tags, write manifests, apply labels, and drive version hierarchies.
- “tests/”: a pytest suite that runs containerized tests against each notebook image.
- “docs/”: Sphinx configuration, static assets, and source for ReadTheDocs.
- “examples/”: sample deploy scripts and manifests (docker-compose, OpenShift S2I, Binder) showing real-world usage.
- “wiki/”: scripts to update the GitHub Wiki from generated manifests.
- CI configuration files (Makefile, .pre-commit, mypy.ini) show linting, typing, and build orchestration.

##### README for additional insights
- The README outlines the publishing flow (build → test → push to Quay.io), supported CPU architectures, and user run-time examples.
- It references external services: GitHub Actions, ReadTheDocs, Binder, Quay.io, Discourse.

##### Capturing essential elements
- Extension points (e.g., new image folders plug into the same build/test loop).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Code
    Repo["Code Repository (GitHub)"]:::source
    click Repo "https://github.com/jupyter/docker-stacks/tree/main//"

    %% CI/CD Orchestration
    CI["CI/CD Orchestration (GitHub Actions)"]:::cicd
    click CI "https://github.com/jupyter/docker-stacks/tree/main/.github/workflows/"
    click CI2 "https://github.com/jupyter/docker-stacks/tree/main/.github/actions/"

    %% Tagging Service
    Tagging["Tagging Service (Python CLI)"]:::service
    click Tagging "https://github.com/jupyter/docker-stacks/tree/main/tagging/"
    click TaggingApps "https://github.com/jupyter/docker-stacks/tree/main/tagging/apps/"
    click TaggingHierarchy "https://github.com/jupyter/docker-stacks/tree/main/tagging/hierarchy/"
    click TaggingManifests "https://github.com/jupyter/docker-stacks/tree/main/tagging/manifests/"
    click TaggingTaggers "https://github.com/jupyter/docker-stacks/tree/main/tagging/taggers/"
    click TaggingUtils "https://github.com/jupyter/docker-stacks/tree/main/tagging/utils/"

    %% Docker Build System
    DockerBuild["Docker Build System"]:::cicd
    click Images "https://github.com/jupyter/docker-stacks/tree/main/images/*-notebook/"
    click BinderDockerfile "https://github.com/jupyter/docker-stacks/tree/main/binder/Dockerfile"

    %% Test Harness
    TestHarness["Test Harness (pytest)"]:::service
    click TestsByImage "https://github.com/jupyter/docker-stacks/tree/main/tests/by_image/"
    click TestsShared "https://github.com/jupyter/docker-stacks/tree/main/tests/shared_checks/"
    click TestsUtils "https://github.com/jupyter/docker-stacks/tree/main/tests/utils/"
    click TestsConftest "https://github.com/jupyter/docker-stacks/blob/main/tests/conftest.py"
    click TestsRunner "https://github.com/jupyter/docker-stacks/blob/main/tests/run_tests.py"
    click PytestIni "https://github.com/jupyter/docker-stacks/blob/main/tests/pytest.ini"

    %% Publish to Registry
    Publish["Publish to Quay.io"]:::artifact
    click PublishWF1 "https://github.com/jupyter/docker-stacks/blob/main/.github/workflows/docker-tag-push.yml"
    click PublishWF2 "https://github.com/jupyter/docker-stacks/blob/main/.github/workflows/docker-build-test-upload.yml"

    Registry["Quay.io Registry"]:::external

    %% Documentation
    DocsBuilder["Documentation Site (Sphinx)"]:::docs
    click Docs "https://github.com/jupyter/docker-stacks/tree/main/docs/"
    click ConfPy "https://github.com/jupyter/docker-stacks/blob/main/docs/conf.py"
    click Static "https://github.com/jupyter/docker-stacks/tree/main/docs/_static/"
    click DocsSources "https://github.com/jupyter/docker-stacks/tree/main/docs/*"
    click ReadTheDocsConfig "https://github.com/jupyter/docker-stacks/blob/main/.readthedocs.yaml"

    RTD["ReadTheDocs"]:::external

    %% Wiki Updater
    WikiUpdater["Wiki Update Tool"]:::service
    click WikiUpd "https://github.com/jupyter/docker-stacks/blob/main/wiki/update_wiki.py"
    click WikiConfig "https://github.com/jupyter/docker-stacks/blob/main/wiki/config.py"
    click WikiTime "https://github.com/jupyter/docker-stacks/blob/main/wiki/manifest_time.py"
    click WikiHome "https://github.com/jupyter/docker-stacks/blob/main/wiki/Home.md"

    Wiki["GitHub Wiki"]:::external

    %% Examples & Binder
    Examples["Examples & Binder Service"]:::docs
    click Examples "https://github.com/jupyter/docker-stacks/tree/main/examples/"
    click BinderDir "https://github.com/jupyter/docker-stacks/tree/main/binder/"

    BinderHub["BinderHub"]:::external

    %% Build Orchestration & Linting
    BuildConfig["Build Orchestration & Linting Config"]:::service
    click Makefile "https://github.com/jupyter/docker-stacks/tree/main/Makefile"
    click Precommit "https://github.com/jupyter/docker-stacks/blob/main/.pre-commit-config.yaml"
    click Mypy "https://github.com/jupyter/docker-stacks/blob/main/mypy.ini"
    click Flake8 "https://github.com/jupyter/docker-stacks/blob/main/.flake8"
    click Hadolint "https://github.com/jupyter/docker-stacks/blob/main/.hadolint.yaml"

    %% Connections
    Repo -->|push commits| CI
    CI -->|runs| Tagging
    CI -->|builds images| DockerBuild
    DockerBuild -->|uses images/*-notebook| TestHarness
    DockerBuild -->|builds binder image| Examples
    CI -->|runs tests| TestHarness
    TestHarness -->|on success| Publish
    Publish -->|push images| Registry
    CI -->|build docs| DocsBuilder
    DocsBuilder -->|publish| RTD
    CI -->|update wiki| WikiUpdater
    WikiUpdater -->|push pages| Wiki
    CI -->|runs lint/mypy| BuildConfig
    Repo -.->|examples usage| Examples
    Examples -->|serves notebooks| BinderHub

    %% Styling
    classDef source fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef cicd fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef service fill:#FFFFE0,stroke:#333,stroke-width:1px;
    classDef artifact fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef docs fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
