# canonical/rockcraft architecture

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

- Interactive diagram: https://gitdiagram.com/canonical/rockcraft
- Repository: https://github.com/canonical/rockcraft

## Overview

##### Project Type and Purpose
- This is a Python-based command-line toolkit and library (“starbase”) that provides the scaffolding, build orchestration, and tooling foundations for Canonical’s Snapcraft-based (Rockcraft) projects.
- It exposes a CLI (`rockcraft`), a core application layer, commands, extension/plugin hooks, services that drive snapshot/OCI builds and remote builds, and a templating system for generating new projects.

##### High‐Level Architectural Components
a. CLI Layer
- `rockcraft/__main__.py` and `rockcraft/cli.py` – entry points and argument parsing via `uv` (a wrapper around click).
b. Core Application
- `rockcraft/application.py` – bootstraps the application, reads configuration, dispatches commands.
- `rockcraft/commands/` – implements each CLI command (e.g., `init`, `build`, `list-extensions`).
c. Extensions & Plugins
- `rockcraft/extensions/` – framework integrations (Django, Flask, Express, Go, FastAPI, etc.).
- `rockcraft/plugins/` – language/build-tool extensions (Maven, Poetry, Python, UVicorn, Ant).
d. Services
- `rockcraft/services/` – core business logic broken into service classes:
– `project` – introspection of existing codebases
– `package` – packaging logic (snapcraft.yaml generation)
– `image` – local OCI image operations
– `remotebuild` – orchestration of remote builds
– `lifecycle` – sequence of steps to assemble layers and overlays
– `provider` / `service_factory` – factory to wire correct service implementations
e. Templating
- `rockcraft/templates/` – Jinja2 templates for each supported framework/language to scaffold a new project or rockcraft.yaml.
f. Data Models & Utilities
- `rockcraft/models/` – in-memory representations (Project, Parts, Layers)
- `rockcraft/utils.py` / `constants.py` / `errors.py` – shared helpers and definitions
g. Configuration & Schema
- `pyproject.toml`, `rockcraft/oci.py`, `schema/rockcraft.json` – define CLI metadata and rockcraft.yaml schema
h. Testing
- `tests/unit/`, `tests/integration/`, `tests/spread/` – layered testing harness that validates commands, services, plugins, and end-to-end spread workflows
i. Documentation & Tooling
- `docs/` (Sphinx): user guides, how-tos, explanations, references
- `tools/` and GitHub Actions workflows – CI, release, linting, docs publishing

##### Relationships & Data Flows
- User ► CLI Layer ► Core Application ► Command Handler
- Command Handler ► Service Factory ► Specific Service ► executes business logic
- Services may:
- Read/write project files (template rendering, overlay steps)
- Invoke Snapcraft / OCI tools (via local hooks or remote API)
- Produce or consume intermediate representations (layers, pebble configs)
- Extensions & Plugins register themselves on startup and hook into service factory or command discovery
- Testing harness injects fake projects into services to validate behavior

##### Architectural Patterns & Design Principles
- Modular layering: CLI | Application core | Commands | Services | Templates
- Inversion of Control: Service Factory binds interfaces to implementations based on project metadata
- Plugin/Extension registration: Discovery via `registry.py` allows new frameworks or build-tools to hook without core changes
- Schema-driven: rockcraft.yaml guided by JSON schema to validate user inputs
- Separation of concerns: templating, business logic, file I/O, external system calls are distinct

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User["User"]:::external -->|uses CLI| CLI_Layer

    %% CLI Layer
    subgraph "CLI Layer"
        CLI_Layer["rockcraft CLI"]:::cli
        CLI_Main["__main__.py"]:::cli
        CLI_CLI["cli.py"]:::cli
    end
    CLI_Layer --> CLI_Main
    CLI_Layer --> CLI_CLI

    %% Core Application
    subgraph "Core Application"
        CoreApp["application.py"]:::core
    end
    CLI_CLI --> CoreApp
    CLI_Main --> CoreApp

    %% Command Modules
    subgraph "Command Modules"
        Commands["commands/"]:::commands
    end
    CoreApp --> Commands

    %% Extensions & Plugins
    subgraph "Extensions Framework"
        ExtRegistry["registry.py"]:::extensions
        ExtExpress["expressjs.py"]:::extensions
        ExtFastAPI["fastapi.py"]:::extensions
        ExtGo["go.py"]:::extensions
        ExtGunicorn["gunicorn.py"]:::extensions
        ExtAppParts["app_parts.py"]:::extensions
    end
    Commands --> ExtRegistry
    ExtRegistry --> ExtExpress
    ExtRegistry --> ExtFastAPI
    ExtRegistry --> ExtGo
    ExtRegistry --> ExtGunicorn
    ExtRegistry --> ExtAppParts

    subgraph "Plugin Implementations"
        PluginAnt["ant_plugin.py"]:::plugins
        PluginMaven["maven_plugin.py"]:::plugins
        PluginPoetry["poetry_plugin.py"]:::plugins
        PluginPython["python_plugin.py"]:::plugins
        PluginUV["uv_plugin.py"]:::plugins
        PluginRegister["register.py"]:::plugins
    end
    ExtRegistry --> PluginRegister
    PluginRegister --> PluginAnt
    PluginRegister --> PluginMaven
    PluginRegister --> PluginPoetry
    PluginRegister --> PluginPython
    PluginRegister --> PluginUV

    %% Service Factory & Providers
    subgraph "Service Factory & Providers"
        ServiceFactory["service_factory.py"]:::services
        Provider["provider.py"]:::services
    end
    CoreApp --> ServiceFactory
    ServiceFactory --> Provider

    %% Service Classes
    subgraph "Services"
        ServiceProject["project.py"]:::services
        ServicePackage["package.py"]:::services
        ServiceImage["image.py"]:::services
        ServiceRemote["remotebuild.py"]:::services
        ServiceLifecycle["lifecycle.py"]:::services
        ServiceInit["init.py"]:::services
    end
    ServiceFactory --> ServiceProject
    ServiceFactory --> ServicePackage
    ServiceFactory --> ServiceImage
    ServiceFactory --> ServiceRemote
    ServiceFactory --> ServiceLifecycle
    ServiceFactory --> ServiceInit

    %% Templating
    subgraph "Templating System"
        Templates["templates/"]:::templates
    end
    ServiceProject --> Templates

    %% Data Models & Utilities
    subgraph "Data Models & Utilities"
        Models["models/"]:::models
        Utils["utils.py"]:::models
        Constants["constants.py"]:::models
        Errors["errors.py"]:::models
    end
    CoreApp --> Models
    CoreApp --> Utils
    CoreApp --> Constants
    CoreApp --> Errors

    %% Configuration & Schema
    subgraph "Configuration & Schema"
        OCIConfig["oci.py"]:::config
        SchemaFile["rockcraft.json"]:::persistent
        PyProject["pyproject.toml"]:::persistent
    end
    CoreApp --> OCIConfig
    CoreApp --> SchemaFile
    CoreApp --> PyProject

    %% Testing Harness
    subgraph "Testing Harness"
        TestsUnit["tests/unit/"]:::testing
        TestsIntegration["tests/integration/"]:::testing
        TestsSpread["tests/spread/"]:::testing
    end
    ServiceProject --> TestsUnit
    ServicePackage --> TestsIntegration
    ServiceInit --> TestsSpread

    %% Documentation & Tooling
    subgraph "Documentation & Tooling"
        DocsSite["docs/"]:::docs
        ToolGenCLI["tools/docs/gen_cli_docs.py"]:::docs
        ToolSchema["tools/schema/schema.py"]:::docs
    end
    CoreApp --> DocsSite
    SchemaFile --> ToolSchema
    CLI_CLI --> ToolGenCLI

    %% Persistent Artifacts
    subgraph "Project Filesystem"
        ProjectFS["templates, overlays, rockcraft.yaml"]:::persistent
    end
    Templates --> ProjectFS
    ServiceLifecycle --> ProjectFS

    %% External Systems
    Snapcraft["Snapcraft Engine"]:::external
    OCIRegistry["OCI Registry"]:::external
    RemoteAPI["Remote Builder API"]:::external
    ReadTheDocs["Read the Docs"]:::external

    ServiceImage -->|push/pull| OCIRegistry
    ServiceRemote -->|calls| RemoteAPI
    ServicePackage -->|invokes| Snapcraft
    DocsSite --> ReadTheDocs

    %% Click Events
    click CLI_Main "https://github.com/canonical/rockcraft/blob/main/rockcraft/__main__.py"
    click CLI_CLI "https://github.com/canonical/rockcraft/blob/main/rockcraft/cli.py"
    click CoreApp "https://github.com/canonical/rockcraft/blob/main/rockcraft/application.py"
    click Commands "https://github.com/canonical/rockcraft/tree/main/rockcraft/commands/"
    click ExtRegistry "https://github.com/canonical/rockcraft/blob/main/rockcraft/extensions/registry.py"
    click ExtExpress "https://github.com/canonical/rockcraft/blob/main/rockcraft/extensions/expressjs.py"
    click ExtFastAPI "https://github.com/canonical/rockcraft/blob/main/rockcraft/extensions/fastapi.py"
    click ExtGo "https://github.com/canonical/rockcraft/blob/main/rockcraft/extensions/go.py"
    click ExtGunicorn "https://github.com/canonical/rockcraft/blob/main/rockcraft/extensions/gunicorn.py"
    click ExtAppParts "https://github.com/canonical/rockcraft/blob/main/rockcraft/extensions/app_parts.py"
    click PluginAnt "https://github.com/canonical/rockcraft/blob/main/rockcraft/plugins/ant_plugin.py"
    click PluginMaven "https://github.com/canonical/rockcraft/blob/main/rockcraft/plugins/maven_plugin.py"
    click PluginPoetry "https://github.com/canonical/rockcraft/blob/main/rockcraft/plugins/poetry_plugin.py"
    click PluginPython "https://github.com/canonical/rockcraft/blob/main/rockcraft/plugins/python_plugin.py"
    click PluginUV "https://github.com/canonical/rockcraft/blob/main/rockcraft/plugins/uv_plugin.py"
    click PluginRegister "https://github.com/canonical/rockcraft/blob/main/rockcraft/plugins/register.py"
    click ServiceFactory "https://github.com/canonical/rockcraft/blob/main/rockcraft/services/service_factory.py"
    click Provider "https://github.com/canonical/rockcraft/blob/main/rockcraft/services/provider.py"
    click ServiceProject "https://github.com/canonical/rockcraft/blob/main/rockcraft/services/project.py"
    click ServicePackage "https://github.com/canonical/rockcraft/blob/main/rockcraft/services/package.py"
    click ServiceImage "https://github.com/canonical/rockcraft/blob/main/rockcraft/services/image.py"
    click ServiceRemote "https://github.com/canonical/rockcraft/blob/main/rockcraft/services/remotebuild.py"
    click ServiceLifecycle "https://github.com/canonical/rockcraft/blob/main/rockcraft/services/lifecycle.py"
    click ServiceInit "https://github.com/canonical/rockcraft/blob/main/rockcraft/services/init.py"
    click Templates "https://github.com/canonical/rockcraft/tree/main/rockcraft/templates/"
    click Models "https://github.com/canonical/rockcraft/tree/main/rockcraft/models/"
    click Utils "https://github.com/canonical/rockcraft/blob/main/rockcraft/utils.py"
    click Constants "https://github.com/canonical/rockcraft/blob/main/rockcraft/constants.py"
    click Errors "https://github.com/canonical/rockcraft/blob/main/rockcraft/errors.py"
    click OCIConfig "https://github.com/canonical/rockcraft/blob/main/rockcraft/oci.py"
    click SchemaFile "https://github.com/canonical/rockcraft/blob/main/schema/rockcraft.json"
    click PyProject "https://github.com/canonical/rockcraft/blob/main/pyproject.toml"
    click TestsUnit "https://github.com/canonical/rockcraft/tree/main/tests/unit/"
    click TestsIntegration "https://github.com/canonical/rockcraft/tree/main/tests/integration/"
    click TestsSpread "https://github.com/canonical/rockcraft/tree/main/tests/spread/"
    click DocsSite "https://github.com/canonical/rockcraft/tree/main/docs/"
    click ToolGenCLI "https://github.com/canonical/rockcraft/blob/main/tools/docs/gen_cli_docs.py"
    click ToolSchema "https://github.com/canonical/rockcraft/blob/main/tools/schema/schema.py"

    %% Styles
    classDef cli fill:#E8F4FD,stroke:#1E4E79,color:#0B2D5C;
    classDef core fill:#F0F8E8,stroke:#3A6F3E,color:#1D3F1E;
    classDef commands fill:#FFF4E6,stroke:#D28200,color:#663C00;
    classDef extensions fill:#F5E8FD,stroke:#7D3F79,color:#4B1E5C;
    classDef plugins fill:#FDE8E8,stroke:#792E2E,color:#5C1A1A;
    classDef services fill:#E8FDF0,stroke:#2E7D3F,color:#1A4B2A;
    classDef templates fill:#FFF8E8,stroke:#A67A00,color:#5C3C00;
    classDef models fill:#E8F0FD,stroke:#2E3F7D,color:#1A244B;
    classDef config fill:#E8F4EC,stroke:#3E7D4A,color:#1F3F22;
    classDef persistent fill:#F0F0F0,stroke:#888888,color:#444444,stroke-dasharray: 5 5;
    classDef testing fill:#F8E8FF,stroke:#5D2E7D,color:#3C1A5C;
    classDef docs fill:#E8FDFD,stroke:#2E7D7D,color:#1A4B4B;
    classDef external fill:#FFE8E8,stroke:#7D2E2E,color:#5C1A1A,shape:cloud;
```
