# cnabio/cnab-go architecture

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

- Interactive diagram: https://gitdiagram.com/cnabio/cnab-go
- Repository: https://github.com/cnabio/cnab-go

## Overview

##### Main Components
- Core CNAB-Go Library: Represent this as the central node providing the main API and orchestration logic.
- Action Module: Include the “action” package which implements operations and orchestration tasks (e.g., execution, upgrade, status queries). Show that this component interacts with several other internal services.
- Claim Module: Represent the “claim” package since it processes bundle claims, installation status, outputs, and results.
- Credentials Module: Include the “credentials” component to show how the system handles different credential sets needed during bundle operations.
- Driver Module: This is important. There are several sub-components – such as command handling (with platform-specific variations like “command_nix” and “command_windows”), Docker integration, Kubernetes drivers, etc. Make sure to indicate that these modules abstract the runtime-specific logic.
- Imagestore Module: Document the “imagestore” section which covers various aspects such as construction, OCI layout conformance, remote interactions, and associated integration tests. This module is essential for container image management per the CNAB spec.
- Schema and Secrets Modules: Represent the “schema” package (for schema definitions and validations) and the “secrets” package (for managing host secrets).
- Value Source Module: Finally, note the “valuesource” package, which provides strategies for extracting or managing runtime values.
- External Dependencies (Optional): You may optionally show external build/integration tools and CI/CD pipelines (e.g., GitHub workflows, Azure Pipelines, Makefile-based operations) that support development, testing, and deployment.

##### Relationships & Interactions
- The CNAB-Go core orchestrates operations by calling functions from the Bundle, Claim, and Action modules.
- The Bundle module validates definitions, utilizes the Replacement submodule and interacts with the Schema module for validating against CNAB schemas.
- The Credentials and Secrets modules are used as auxiliary services by other modules (e.g., when launching new bundles/cliams).
- The Packager module can be represented as a helper that converts bundles into deployable artifacts, feeding into the Imagestore module that manages OCI image layouts.

##### Architectural Patterns & Design Principles
- Modular design, where each package is a self-contained component with well-defined interfaces.
- The separation of concerns is evident—operations like parsing and validating bundle definitions are separated from runtime actions.
- The design also encourages extensibility, as seen with multiple drivers catering to different environments. Illustrate this with a “Strategy” pattern for the Value Source module and a plug-in like structure for different drivers.

- Another for support utilities (e.g., Credentials, Secrets, Schema, Valuesource),
- And a third for external integrations and CI/CD support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Integrations
    cicd["CI/CD Pipelines"]:::external
    runtime["Runtime Environment"]:::external

    %% Core Library
    subgraph "Core Library"
        core["CNAB-Go Core Library"]:::business
    end

    %% Business Logic Modules
    subgraph "Business Logic Modules"
        action["Action Module"]:::business
        bundle["Bundle Module"]:::business
        claim["Claim Module"]:::business
        driver["Driver Module"]:::business
        imagestore["Imagestore Module"]:::business
        packager["Packager Module"]:::business
    end

    %% Support Utilities
    subgraph "Support Utilities"
        credentials["Credentials Module"]:::support
        schema["Schema Module"]:::support
        secrets["Secrets Module"]:::support
        valuesource["Value Source Module"]:::support
    end

    %% Relationships and Data Flow
    cicd -->|"build_and_test"| core

    core -->|"orchestrates"| action
    core -->|"orchestrates"| bundle
    core -->|"orchestrates"| claim
    core -->|"orchestrates"| driver
    core -->|"orchestrates"| imagestore
    core -->|"orchestrates"| packager

    action -->|"delegates_command"| driver
    action -->|"loads_bundle"| bundle

    bundle -->|"validates_against"| schema

    packager -->|"exports_bundle"| imagestore

    core -->|"uses_credentials"| credentials
    core -->|"uses_secrets"| secrets
    core -->|"extracts_values"| valuesource

    driver -->|"executes_on"| runtime

    %% Styles
    classDef business fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef support fill:#C1E1C1,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;

    %% Click Events
    click action "https://github.com/cnabio/cnab-go/blob/main/action/action.go"
    click bundle "https://github.com/cnabio/cnab-go/tree/main/bundle/"
    click claim "https://github.com/cnabio/cnab-go/blob/main/claim/claim.go"
    click credentials "https://github.com/cnabio/cnab-go/blob/main/credentials/credentialset.go"
    click driver "https://github.com/cnabio/cnab-go/blob/main/driver/command/command.go"
    click imagestore "https://github.com/cnabio/cnab-go/tree/main/imagestore/construction"
    click packager "https://github.com/cnabio/cnab-go/blob/main/packager/export.go"
    click schema "https://github.com/cnabio/cnab-go/blob/main/schema/schema/bundle.schema.json"
    click secrets "https://github.com/cnabio/cnab-go/blob/main/secrets/host/host.go"
    click valuesource "https://github.com/cnabio/cnab-go/blob/main/valuesource/strategy.go"
    click cicd "https://github.com/cnabio/cnab-go/tree/main/.github/"
```
