# docker/buildx architecture

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

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

## Overview

##### Main Components
- CLI/Command Layer: Represented by the “cmd” and “commands” directories. This layer serves as the entry point for user interactions (e.g., docker buildx build, create, ls, etc.).
- Controller Layer: Found in the “controller” directory, which includes modules for build management, error definitions, remote and local controllers. This layer orchestrates command requests and enforces business logic.
- Builder & High-Level Construct Layer: The “builder” and “bake” directories encapsulate logic for handling build instances and high-level build constructs (e.g., “bake” makes it easier to work with complex build configurations).
- Driver Layer: The “driver” directory contains multiple subdirectories with specific drivers (docker, docker-container, kubernetes, remote, etc.). These drivers abstract the interactions with various backends (BuildKit, Docker daemon, Kubernetes clusters).
- Utils and Store: Supporting packages (like “util”, “store”, “localstate”) provide configuration handling, state management, logging, and various helper functionalities.
- Infrastructure/Testing/Docs Layers: The project also includes a “tests” folder for integration/unit tests, “docs” for reference materials, and GitHub workflows/configurations for CI/CD.

##### Relationships and Interactions
- The CLI layer dispatches user commands to the “commands” modules (and from there to individual subcommands like “build”, “create”, “ls”, etc.).
- These commands interact with the Controller layer to manage builder instances, initiate builds, and process build configurations.
- The Controller invokes the appropriate Driver(s) based on the active builder instance. Drivers then take over to interact with low-level Docker and infrastructure layers.
- The “bake” component offers a high-level declarative approach to define multi-target/multi-node builds; it integrates with the builder and controller layers.
- Utility packages facilitate common tasks such as configuration parsing (e.g., HCL parsing in “bake/hclparser”), logging, tracing, and interaction with external services (e.g., Kubernetes clusters).

##### Architectural Patterns and Design Principles
- Layered Architecture: Separation of concerns is evident with distinct folders for the CLI, controllers, drivers, and utility functions.
- Abstraction and Extension: Drivers and controllers are abstracted to support multiple backends (Docker, Kubernetes, remote nodes). This allows for plug-and-play extensibility.
- Testing and CI/CD: Comprehensive use of tests and GitHub workflows indicates an emphasis on continuous integration and reliable releases.

##### Relevant Technologies/Frameworks
- Go (the primary language), along with specific Go modules for CLI design (likely using Cobra, as seen in “util/cobrautil”), configuration (HCL parsing), and gRPC (see “controller/pb” files).
- BuildKit as the backend engine for builds.
- Docker and Kubernetes APIs/interfaces are integrated as part of the driver implementations.
- Container orchestration utilities, Dockerfile multi-stage builds, and QEMU for cross-platform emulation are supported.

##### Elements
- “CLI & Commands” (cmd, commands)
- “Controller & Orchestration” (controller folder, builder)
- “High-Level Build Constructs” (“bake” components)
- “Drivers” (docker, docker-container, kubernetes, remote subcomponents)
- “Utilities/Support” (util, store, localstate)
- “Documentation & Testing” (docs, tests)
- Data flow from user input through the CLI/commands to the controllers, then to the driver layer.
- Control flows for operations such as creating builder instances, managing builds, and selecting driver-specific actions.
- Distinct Visual Differentiation:

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Initiator
    User["User"]:::external

    %% CLI & Commands Layer
    subgraph "CLI & Commands"
        Cmd["cmd"]:::cli
        Commands["commands"]:::cli
    end

    %% Controller & Orchestration Layer
    Controller["controller"]:::controller

    %% Builder & High-Level Build Constructs Layer
    subgraph "Build Constructs"
        Builder["builder"]:::builder
        Bake["bake"]:::builder
    end

    %% Driver Layer
    Driver["driver"]:::driver

    %% Utilities & Support Layer
    subgraph "Utilities & Support"
        Util["util"]:::utils
        Store["store"]:::utils
        LocalState["localstate"]:::utils
    end

    %% Documentation & Testing Layer
    subgraph "Documentation & Testing"
        Docs["docs"]:::docs
        Tests["tests"]:::docs
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Docker["Docker Engine"]:::external
        Kubernetes["Kubernetes Cluster"]:::external
        BuildKit["BuildKit"]:::external
    end

    %% Flow Connections
    User -->|"triggers"| Cmd
    User -->|"triggers"| Commands

    Cmd -->|"sends_commands"| Controller
    Commands -->|"sends_subcommands"| Controller

    Controller -->|"manages"| Builder
    Controller -->|"orchestrates"| Bake

    Builder -->|"selects_driver"| Driver
    Bake -->|"integrates_driver"| Driver

    Driver -->|"communicates_with"| Docker
    Driver -->|"communicates_with"| Kubernetes
    Driver -->|"communicates_with"| BuildKit

    %% Support Relationships (dashed lines)
    Util -.-> Controller
    Store -.-> Builder
    LocalState -.-> Controller

    %% Click Events for Component Mapping
    click Cmd "https://github.com/docker/buildx/tree/master/cmd/"
    click Commands "https://github.com/docker/buildx/tree/master/commands/"
    click Controller "https://github.com/docker/buildx/tree/master/controller/"
    click Builder "https://github.com/docker/buildx/tree/master/builder/"
    click Bake "https://github.com/docker/buildx/tree/master/bake/"
    click Driver "https://github.com/docker/buildx/tree/master/driver/"
    click Util "https://github.com/docker/buildx/tree/master/util/"
    click Store "https://github.com/docker/buildx/tree/master/store/"
    click LocalState "https://github.com/docker/buildx/tree/master/localstate/"
    click Docs "https://github.com/docker/buildx/tree/master/docs/"
    click Tests "https://github.com/docker/buildx/tree/master/tests/"

    %% Styles
    classDef cli fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef controller fill:#87CEEB,stroke:#4682B4,stroke-width:2px;
    classDef builder fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef driver fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef utils fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef docs fill:#E6E6FA,stroke:#8A2BE2,stroke-width:2px;
    classDef external fill:#FFFFE0,stroke:#DAA520,stroke-width:2px;
```
