# shipwright-io/build architecture

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

- Interactive diagram: https://gitdiagram.com/shipwright-io/build
- Repository: https://github.com/shipwright-io/build

## Overview

##### Main Components
- Build Controller & Reconcilers: This is the core component, found in pkg/controller and pkg/reconciler. It orchestrates custom resources (Build, BuildRun, BuildStrategy, and ClusterBuildStrategy) and implements the control loop pattern.
- CRDs & API Schemas: Located in deploy/crds and pkg/apis, these define the custom resource definitions corresponding to the Shipwright API (e.g., build and buildrun objects).
- Command Line Tools and Entrypoints: Under the cmd folder, there are multiple binaries (such as “bundle”, “git”, “image-processing”, “waiter”, and webhooks). These represent specific runtime executables that start different aspects of Shipwright (e.g., controller, webhook serving, or auxiliary tooling).
- Client Libraries and Informers: Under pkg/client and pkg/client/informers (and corresponding “listers”), these provide necessary convenience abstractions to interact with the Kubernetes API server for working with the custom resources.
- Webhook Component: In pkg/webhook (and in cmd/shipwright-build-webhook) covers dynamic conversion or validation tasks, ensuring that CRD changes are applied correctly.
- Image Processing and Git Integration Modules: Seen in pkg/image and pkg/git, these components handle specialized tasks such as mutating or processing images and interfacing with Git repositories.
- Deployment & Infrastructure Files: The deploy directory houses YAMLs that set up namespaces, roles, service accounts, and the controllers themselves in a Kubernetes cluster.

##### Relationships/Interactions Between Components
- Controllers (in pkg/controller/reconciler) watch the Kubernetes API for changes in custom resources. They use client libraries (informers, listers) to efficiently “observe” Build, BuildRun, etc.
- When a user creates a Build CR (via YAML deployment as detailed in the README), the controller picks it up, reconciles its desired state, and triggers associated actions (like starting a BuildRun).
- The webhook (packaged as cmd/shipwright-build-webhook and code in pkg/webhook) validates and/or converts incoming requests to the correct API version.
- The command-line tools (cmd/git, cmd/image-processing) executed in containers (whose Dockerfiles are in images/*) perform isolated tasks (e.g., fetching source code, mutating OCI images) as part of the build process.
- External integrations (container registries, Tekton Pipelines) are indirectly reached via the Build strategies that call out to these tools – as referenced in the README instructions.

##### Architectural Patterns & Design Principles
- Kubernetes Controller Pattern: The system heavily relies on CRDs, informers, listers and reconcilers to observe and act upon changes in the cluster.
- Modular Design: Separation of functionalities (APIs, controllers, webhooks, stand-alone command line tools) across subdirectories promotes maintainability and independent evolution.
- Extensibility: The project supports multiple build strategies by having a flexible API design and a pluggable reconciling mechanism.
- Continuous Integration & Development: Presence of extensive test directories (test/e2e, test/integration) and CI workflow configurations in /.github shows a commitment to automated testing and deployment practices.

##### Relevant Technologies/Frameworks
- Kubernetes (with Custom Resource Definitions)
- Tekton Pipelines, which is a key dependency for build process execution
- Go modules for dependency management (go.mod, go.sum)
- Container images built using Dockerfiles under images/*
- Git for source code versioning (cmd/git, pkg/git)

- Maintain clarity by grouping related components (for example, grouping all client libraries and informers together) so that the interactions are obvious.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction"
        U("User / Git Repository"):::user
    end

    %% Kubernetes Cluster Layer
    subgraph "Kubernetes Cluster"
        %% Control Plane Components
        subgraph "Control Plane"
            CRD("Kubernetes API Server (CRDs & API Schemas)"):::crd
            D("Deployment & Infrastructure"):::deployment
        end

        %% Controller Layer
        subgraph "Controller Layer"
            CONT("Shipwright Build Controller & Reconcilers"):::controller
            CLI("Client Libraries & Informers"):::client
            WH("Shipwright Webhook"):::webhook
        end

        %% Command-line Tools Layer
        subgraph "Command-line Tools"
            BUNDLE("Bundle Tool"):::tool
            GIT("Git Tool"):::tool
            IMAGE("Image Processing Tool"):::tool
            WAITER("Waiter Tool"):::tool
        end

        %% Internal Modules
        subgraph "Internal Modules"
            IMG("Image Processing Module"):::module
            GITMOD("Git Integration Module"):::module
        end
    end

    %% External Systems
    subgraph "External Systems"
        EXT("Container Registry & Tekton Pipelines"):::external
    end

    %% Connections
    U -->|"sends"| CRD
    D -->|"configures"| CRD
    CRD -->|"observes"| CONT
    CONT -->|"uses"| CLI
    CONT -->|"validates"| WH
    CONT -->|"invokes"| BUNDLE
    CONT -->|"invokes"| GIT
    CONT -->|"invokes"| IMAGE
    CONT -->|"invokes"| WAITER
    CONT -->|"calls"| EXT
    GIT -->|"utilizes"| GITMOD
    IMAGE -->|"utilizes"| IMG

    %% Styles
    classDef user fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef crd fill:#AFEEEE,stroke:#333,stroke-width:2px;
    classDef deployment fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef controller fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef client fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef webhook fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef tool fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef external fill:#FFDEAD,stroke:#333,stroke-width:2px;
    classDef module fill:#E6E6FA,stroke:#333,stroke-width:2px;

    %% Click Events
    click CONT "https://github.com/shipwright-io/build/blob/main/cmd/shipwright-build-controller/main.go"
    click CRD "https://github.com/shipwright-io/build/tree/main/deploy/crds"
    click CLI "https://github.com/shipwright-io/build/tree/main/pkg/client"
    click WH "https://github.com/shipwright-io/build/blob/main/cmd/shipwright-build-webhook/main.go"
    click BUNDLE "https://github.com/shipwright-io/build/blob/main/cmd/bundle/main.go"
    click GIT "https://github.com/shipwright-io/build/blob/main/cmd/git/main.go"
    click IMAGE "https://github.com/shipwright-io/build/blob/main/cmd/image-processing/main.go"
    click WAITER "https://github.com/shipwright-io/build/blob/main/cmd/waiter/main.go"
    click IMG "https://github.com/shipwright-io/build/blob/main/pkg/image/mutate.go"
    click GITMOD "https://github.com/shipwright-io/build/blob/main/pkg/git/git.go"
    click D "https://github.com/shipwright-io/build/tree/main/deploy"
```
