# dusty-nv/jetson-containers architecture

> Architecture diagram of the GitHub repository dusty-nv/jetson-containers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dusty-nv/jetson-containers
- Repository: https://github.com/dusty-nv/jetson-containers

## Overview

##### Project Type & Purpose
- This is a modular, CLI-driven container build system (“jetson-containers”) written in Python, augmented by shell scripts, for assembling and running AI/ML Docker images on NVIDIA Jetson hardware.
- It exposes commands like `jetson-containers build`, `run`, and `autotag`, reads package definitions from the `packages/` folder, and orchestrates Docker builds, pulls, and runs with configured defaults (e.g., NVIDIA runtime, mounted volumes, CUDA versions).

##### Top-Level Components
a. CLI Frontend
- Entry point scripts (`run.sh`, `build.sh`, `autotag`, `install.sh`) wrap the Python package.
- Shell commands parse user flags & environment variables, invoke Python modules.
b. Core Python Engine (`jetson_containers/`)
- container.py: interfaces with Docker CLI/daemon (build, tag, run)
- build.py: dependency resolution, multi-stage build orchestration
- db.py: local metadata/graph of package definitions (`packages/*/*.json`, `data/containers.json`)
- network.py: pulls/pushes images from registries, pip server interactions
- packages.py: plugin loader for each package subdirectory (defines Dockerfiles, scripts)
- ci.py: helpers for GitHub Actions workflows
- utils.py & logging.py: shared utilities, standardized logging
c. Package Definitions (`packages/…`)
- Hundreds of subfolders grouping categories (llm, ml, cv, llm, speech, robotics, etc.)
- Each contains Dockerfile(s), build/install scripts, config metadata, and tests.
d. Local Data & Config
- `.env`, `.env_sample` for version pins (CUDA, Python, cuDNN)
- `data/` for caching: model files, audio, prompts, logs, container DB snapshots
- `docs/` for end-user documentation; `.github/workflows/` for CI pipelines
e. External Services & Dependencies
- Docker daemon (local)
- Container registries (Docker Hub, GHCR, custom Pip index)
- GitHub Actions for CI building/testing on commits
- NVIDIA Jetson hardware (edge target)

##### Interactions & Data Flow
- User invokes CLI script → Frontend shell parses env/args → Python CLI entrypoint
- CLI reads `.env`, resolves package names → queries `db.py` for dependency graph
- `build.py` orchestrates build order, invokes Docker builds (via container.py)
- Docker daemon performs image layers, caches, tags images → optional push to registry
- `network.py` handles pulls of base images and pushes of completed images
- Data/metadata updates written back to `data/containers.json` and logs in `data/logs/`
- `run` command uses container.py to launch `docker run` with GPU runtime and mounts

##### Architectural Patterns & Principles
- Plugin-based architecture: each package folder self-describes build steps
- Layered abstraction over Docker CLI: container.py sits between build logic & Docker
- Dependency graph resolution: build.py ensures correct build order and caching
- Environment-driven configuration: `.env`, CLI flags, and scripts configure behavior
- Composition over monolith: users “compose” containers by name (e.g., pytorch + ros)

##### Relevant Technologies & Frameworks
- Language: Python 3.x
- Containers: Docker Engine with NVIDIA runtime
- CI: GitHub Actions (YAML workflows in `.github/workflows/`)
- Shell: bash build/install wrappers
- Data format: JSON for metadata, YAML for system configs (`docker-compose.yaml`)
- External APIs: Docker REST/CLI, GitHub, custom PyPI index

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User triggers
    User["User"]:::external
    %% CLI Frontend
    subgraph "CLI Frontend"
        run_sh["run.sh"]:::cli
        build_sh["build.sh"]:::cli
        autotag["autotag"]:::cli
        install_sh["install.sh"]:::cli
    end
    %% Core Engine
    subgraph "Core Engine"
        core_cli["Python CLI Entrypoint"]:::core
        build_py["Build Orchestrator\n(jetson_containers/build.py)"]:::core
        container_py["Container Manager\n(jetson_containers/container.py)"]:::core
        db_py["Package DB\n(jetson_containers/db.py)"]:::core
        network_py["Network Handler\n(jetson_containers/network.py)"]:::core
        packages_py["Plugin Loader\n(jetson_containers/packages.py)"]:::core
        ci_py["CI Helpers\n(jetson_containers/ci.py)"]:::core
        utils_py["Utilities\n(jetson_containers/utils.py)"]:::core
        logging_py["Logging\n(jetson_containers/logging.py)"]:::core
        tag_py["Tagging\n(jetson_containers/tag.py)"]:::core
        pypi_utils_py["PyPI Utils\n(jetson_containers/pypi_utils.py)"]:::core
        l4t_version_py["L4T Version\n(jetson_containers/l4t_version.py)"]:::core
        l4t_version_sh["L4T Version Script\n(jetson_containers/l4t_version.sh)"]:::core
    end
    %% Package Definition Store
    subgraph "Package Definition Store"
        packages_dir["packages/"]:::filesystem
    end
    %% Local Data & Config
    subgraph "Local Data & Config"
        env[".env / .env_sample"]:::filesystem
        data_dir["data/"]:::filesystem
        containers_json["data/containers.json"]:::filesystem
    end
    %% CI Pipelines
    workflows[".github/workflows/"]:::filesystem
    %% External Services
    subgraph "External Services"
        docker["Docker Daemon"]:::external
        registry["Container Registry"]:::external
        pip_server["Pip Server"]:::external
        jetson_hw["NVIDIA Jetson Hardware"]:::external
        github_actions["GitHub Actions"]:::external
    end

    %% Flows
    User -->|invokes| run_sh
    User --> build_sh
    User --> autotag
    User --> install_sh

    run_sh --> core_cli
    build_sh --> core_cli
    autotag --> core_cli
    install_sh --> core_cli

    env --> core_cli

    core_cli --> db_py
    core_cli --> network_py
    core_cli --> ci_py

    db_py --> build_py
    build_py --> container_py
    build_py --> packages_py
    packages_py --> packages_dir

    build_py -->|writes metadata| containers_json
    build_py -->|caches data| data_dir

    container_py --> docker
    docker <--> registry
    network_py <--> registry
    network_py <--> pip_server

    container_py -->|docker run| jetson_hw

    workflows --> ci_py
    ci_py --> build_py
    ci_py --> container_py

    %% Click Events
    click run_sh "https://github.com/dusty-nv/jetson-containers/blob/master/run.sh"
    click build_sh "https://github.com/dusty-nv/jetson-containers/blob/master/build.sh"
    click autotag "https://github.com/dusty-nv/jetson-containers/tree/master/autotag"
    click install_sh "https://github.com/dusty-nv/jetson-containers/blob/master/install.sh"
    click build_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/build.py"
    click container_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/container.py"
    click db_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/db.py"
    click containers_json "https://github.com/dusty-nv/jetson-containers/blob/master/data/containers.json"
    click network_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/network.py"
    click packages_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/packages.py"
    click packages_dir "https://github.com/dusty-nv/jetson-containers/tree/master/packages/"
    click ci_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/ci.py"
    click workflows "https://github.com/dusty-nv/jetson-containers/tree/master/.github/workflows/"
    click utils_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/utils.py"
    click logging_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/logging.py"
    click tag_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/tag.py"
    click pypi_utils_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/pypi_utils.py"
    click l4t_version_py "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/l4t_version.py"
    click l4t_version_sh "https://github.com/dusty-nv/jetson-containers/blob/master/jetson_containers/l4t_version.sh"
    click env "https://github.com/dusty-nv/jetson-containers/blob/master/.env"

    %% Styles
    classDef cli fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef core fill:#E8F5E9,stroke:#81C784,color:#1B5E20;
    classDef filesystem fill:#FFF3E0,stroke:#FFB74D,color:#E65100;
    classDef external fill:#F3E5F5,stroke:#CE93D8,color:#4A148C;
```
