# buildpacks/pack architecture

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

- Interactive diagram: https://gitdiagram.com/buildpacks/pack
- Repository: https://github.com/buildpacks/pack

## Overview

##### Project type and purpose
- This is a full-featured CLI tool written in Go (“pack”) that implements the Cloud Native Buildpacks Platform Interface.
- It provides commands to build images, manage buildpacks and builders, inspect images, and interact with registries and container runtimes.

##### File structure
- Top-level:
- cmd/ and main.go: the CLI entrypoint and command wiring.
- internal/commands/: per-subcommand handlers.
- pkg/: reusable client libraries (archive, blob, buildpack, cache, client, dist, image, index, logging, project, etc.).
- internal/build and internal/builder: orchestrate the build lifecycle.
- acceptance/: end-to-end tests that spin up Docker, fetch buildpacks and stacks.
- Dockerfile, Makefile, workflows: build and release automation.
- Patterns:
- Modular layering: “pkg” holds domain libraries, “internal” holds orchestration and CLI-exclusive code.
- Factory/providers: e.g., writer_factory, label_manager_provider.
- Command pattern via subpackages in internal/commands.
- Client/server interaction: pack talks to Docker daemon (container_ops.go, docker.go) and remote registries (registry/*, client/docker, blob/downloader).

##### README for additional insights
- Describes that “pack” is a CLI for app developers, buildpack authors, and operators.
- It implements the CNB platform spec.
- Emphasizes interaction with buildpacks, builders, container runtimes, and OCI registries.

##### Main components
a. Components
1. CLI Frontend
- main.go → cmd package → Cobra commands
2. Command Handlers
- internal/commands/* implements subcommands (build, inspect, config, builder_*, buildpack_*, etc.)
3. Core Services (pkg/*)
- pkg/client: high-level client API
- pkg/archive, pkg/blob, pkg/cache, pkg/buildpack, pkg/image, pkg/index, pkg/dist, pkg/project, pkg/logging
4. Build Orchestration
- internal/build: runs lifecycle phases in containers
- internal/builder: computes buildpack detection order, invokes lifecycle binaries
5. Container Runtime
- Docker daemon (via Docker socket)
6. OCI Registry(s)
- Remote image and buildpack registries (Docker Hub, GitHub Packages, custom registries)
7. File System / Local Assets
- project.toml, buildpack folders, stack images, local caches
8. External Services
- GitHub Asset Fetcher, registry index files, Cloud Native Buildpacks lifecycle images
9. Tests & CI
- acceptance tests spin up containers and mock registries
- GitHub Actions workflows for build, release, packaging (Homebrew, Chocolatey, Ubuntu PPA, Arch Linux, Docker, etc.)

b. Relationships & Interactions
- CLI Frontend receives user input → dispatches to a subcommand handler
- Command Handler uses pkg/client or internal services
- pkg/client orchestrates:
- local asset discovery (pkg/project)
- downloading blobs (pkg/blob)
- invoking Docker for build (internal/build/container_ops → Docker API)
- pushing/pulling to registries (pkg/index, pkg/image)
- internal/build invokes lifecycle binaries inside ephemeral containers
- registry/* resolves buildpack/builder locations and metadata
- Logging flows from packages → termui or simple logger
- CI/CD workflows build/test the CLI, publish binaries and packages

c. Architectural patterns & principles
- Layered architecture: CLI → commands → client libraries → OS/external dependencies
- Dependency inversion: pkg interfaces abstract Docker and registry clients for testability
- Factory pattern: for writers, label managers, blob downloaders
- Test doubles: extensive use of fakes in internal/fakes and pkg/testmocks
- Single responsibility: each pkg and internal subpackage has a focused role

d. Key technologies & frameworks
- Go language, Go modules
- Cobra (for CLI parsing)
- Docker Engine API
- OCI image spec, Docker registry spec
- Cloud Native Buildpacks Platform spec
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        User["User"]:::external
        CLI["main.go\ncmd package"]:::cli
        DockerInit["cmd/docker_init.go"]:::cli
    end

    %% Command Handlers
    subgraph "Command Handlers"
        CmdHandlers["internal/commands/*"]:::intern
    end

    %% Client Libraries
    subgraph "Client Libraries"
        ClientAPI["pkg/client/client.go"]:::libs
        BuildAPI["pkg/client/build.go"]:::libs
        BuildpackLib["pkg/buildpack/"]:::libs
        ArchiveLib["pkg/archive/archive.go"]:::libs
        BlobLib["pkg/blob/downloader.go"]:::libs
        CacheLib["pkg/cache/cache_opts.go"]:::libs
        ImageLib["pkg/image/fetcher.go\npkg/image/pull_policy.go"]:::libs
        IndexLib["pkg/index/index_factory.go"]:::libs
        DistLib["pkg/dist/dist.go"]:::libs
        ProjectLib["pkg/project/project.go"]:::libs
        LoggingLib["pkg/logging/logging.go"]:::libs
    end

    %% Internal Services
    subgraph "Internal Services"
        BuildOrch["internal/build/lifecycle_executor.go"]:::intern
        ContainerOps["internal/build/container_ops.go"]:::intern
        BuilderComp["internal/builder/detection_order_calculator.go\ninternal/builder/lifecycle.go"]:::intern
        RegResolvers["internal/registry/github.go\ninternal/registry/git.go"]:::intern
        Paths["internal/paths/paths.go"]:::intern
    end

    %% External Systems
    subgraph "External Systems"
        DockerDaemon["Docker Daemon"]:::external
        Registries["OCI Registries\n(GitHub, Docker Hub)"]:::external
        GitHubFetcher["GitHub Asset Fetcher"]:::external
        LifecycleImgs["CNB Lifecycle Images"]:::external
        FileSystem["Local FS\n(project.toml, caches)"]:::external
    end

    %% Tests & CI
    subgraph "Tests & CI"
        AcceptanceTests["acceptance/acceptance_test.go"]:::testci
        CIWorkflows[".github/workflows/*.yml"]:::testci
    end

    %% Connections
    User -->|invokes| CLI
    CLI -->|wires commands| DockerInit
    CLI -->|dispatches| CmdHandlers
    CmdHandlers -->|uses| ClientAPI
    ClientAPI -->|build| BuildAPI
    ClientAPI -->|manage blobs| BlobLib
    ClientAPI -->|archive ops| ArchiveLib
    ClientAPI -->|cache ops| CacheLib
    ClientAPI -->|image pull/fetch| ImageLib
    ClientAPI -->|registry index| IndexLib
    ClientAPI -->|dist descriptors| DistLib
    ClientAPI -->|project parsing| ProjectLib
    ClientAPI -->|logging| LoggingLib
    CmdHandlers -->|orchestrates| BuildOrch
    BuildOrch -->|exec phases| ContainerOps
    BuildOrch -->|compute order| BuilderComp
    ContainerOps -->|talks to| DockerDaemon
    BuilderComp -->|runs lifecycle| LifecycleImgs
    ClientAPI -->|resolve registry| RegResolvers
    RegResolvers -->|interacts with| Registries
    ProjectLib -->|reads/writes| FileSystem
    CacheLib -->|stores/loads| FileSystem

    AcceptanceTests -->|test flow| DockerDaemon
    AcceptanceTests -->|test flow| Registries
    CIWorkflows -->|CI/CD| CLI

    %% Click Events
    click CLI "https://github.com/buildpacks/pack/blob/main/main.go"
    click DockerInit "https://github.com/buildpacks/pack/blob/main/cmd/docker_init.go"
    click CmdHandlers "https://github.com/buildpacks/pack/tree/main/internal/commands/"
    click ClientAPI "https://github.com/buildpacks/pack/blob/main/pkg/client/client.go"
    click BuildAPI "https://github.com/buildpacks/pack/blob/main/pkg/client/build.go"
    click BuildpackLib "https://github.com/buildpacks/pack/tree/main/pkg/buildpack/"
    click ArchiveLib "https://github.com/buildpacks/pack/blob/main/pkg/archive/archive.go"
    click BlobLib "https://github.com/buildpacks/pack/blob/main/pkg/blob/downloader.go"
    click CacheLib "https://github.com/buildpacks/pack/blob/main/pkg/cache/cache_opts.go"
    click ImageLib "https://github.com/buildpacks/pack/blob/main/pkg/image/fetcher.go"
    click ImageLib "https://github.com/buildpacks/pack/blob/main/pkg/image/pull_policy.go"
    click IndexLib "https://github.com/buildpacks/pack/blob/main/pkg/index/index_factory.go"
    click DistLib "https://github.com/buildpacks/pack/blob/main/pkg/dist/dist.go"
    click ProjectLib "https://github.com/buildpacks/pack/blob/main/pkg/project/project.go"
    click LoggingLib "https://github.com/buildpacks/pack/blob/main/pkg/logging/logging.go"
    click BuildOrch "https://github.com/buildpacks/pack/blob/main/internal/build/lifecycle_executor.go"
    click ContainerOps "https://github.com/buildpacks/pack/blob/main/internal/build/container_ops.go"
    click BuilderComp "https://github.com/buildpacks/pack/blob/main/internal/builder/detection_order_calculator.go"
    click BuilderComp "https://github.com/buildpacks/pack/blob/main/internal/builder/lifecycle.go"
    click RegResolvers "https://github.com/buildpacks/pack/blob/main/internal/registry/github.go"
    click RegResolvers "https://github.com/buildpacks/pack/blob/main/internal/registry/git.go"
    click Paths "https://github.com/buildpacks/pack/blob/main/internal/paths/paths.go"
    click AcceptanceTests "https://github.com/buildpacks/pack/blob/main/acceptance/acceptance_test.go"
    click CIWorkflows "https://github.com/buildpacks/pack/blob/main/.github/workflows/build.yml"
    click CIWorkflows "https://github.com/buildpacks/pack/blob/main/.github/workflows/delivery-*.yml"

    %% Styles
    classDef cli fill:#d1e8ff,stroke:#333,stroke-width:1px
    classDef libs fill:#e8f5e9,stroke:#333,stroke-width:1px
    classDef intern fill:#fff3e0,stroke:#333,stroke-width:1px
    classDef external fill:#f3e5f5,stroke:#333,stroke-width:1px
    classDef testci fill:#eceff1,stroke:#333,stroke-width:1px
```
