# cabinpkg/cabin architecture

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

- Interactive diagram: https://gitdiagram.com/cabinpkg/cabin
- Repository: https://github.com/cabinpkg/cabin

## Overview

##### Project type and purpose
- From the file tree and README, this is “Cabin”: a standalone, command-line package manager and build system for C++ projects (akin to Rust’s Cargo). It’s written in C++ and manages project initialization, dependency resolution, building, testing, publishing, etc.

##### File structure
- Top-level:
- src/ – all C++ sources, organized into sub-modules:
– Cli/ and Cmd/ – command dispatcher and individual CLI commands (Add, Build, Init, Run, etc.)
– Builder/ – core build engine (BuildConfig, Compiler, Project, BuildProfile)
– Git2/ – libgit2 wrappers for Git operations
– GraphQL/ – GraphQL package-registry queries (SearchPackages.gql) via libcurl
– Manifest, Dependency, Semver, VersionReq, Parallelism, Algos – dependency graph, version resolution, parallel build orchestration
– Rustify – code-generation helpers (e.g., generating Rust-style data structures)
– main.cc – entry point
- tests/ – end-to-end shell scripts validating each command
- docs/, mkdocs.yml – user documentation site
- CI/.github/workflows – GitHub Actions for building, testing, releasing, docker, docs
- Dockerfile, Makefile, INSTALL.md – local build instructions
- Configuration files: cabin.toml (package manifest), .clang-format, .clang-tidy

##### README for additional insights
- Confirms that Cabin:
- Is self-buildable
- Minimizes manual configuration, using filesystem conventions (Cargo-style)
- Interacts with a remote package registry over GraphQL
- Uses Git remotes to fetch sources

##### Diagramming recommendations
- User → CLI Front-end
- CLI → Builder API → HTTP / Git2 → external services
- Builder → system compiler → artifacts → filesystem
- Diagnostics back from modules → CLI → User

##### Essential elements
- Component labels (e.g., “Cmd::Add”, “BuildConfig”)
- Notes on concurrency: highlight `Parallelism` module driving multi-threaded builds

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::user

    %% CLI Layer
    subgraph "CLI Front-end"
        direction TB
        Main["main.cc"]:::cli
        CliCC["Cli.cc"]:::cli
        CliHPP["Cli.hpp"]:::cli
        CommandCC["Command.cc"]:::cli
        CommandHPP["Command.hpp"]:::cli
        subgraph "Cmd Commands"
            direction TB
            CmdAdd["Add (Cmd/Add.cc)"]:::cli
            CmdBuild["Build (Cmd/Build.cc)"]:::cli
            CmdInit["Init (Cmd/Init.cc)"]:::cli
            CmdRun["Run (Cmd/Run.cc)"]:::cli
            %% more commands...
        end
    end

    %% Core Build Engine
    subgraph "Core Build Engine"
        direction TB
        BuildConfigCC["BuildConfig.cc"]:::core
        BuildConfigHPP["BuildConfig.hpp"]:::core
        ProjectCC["Project.cc"]:::core
        ProjectHPP["Project.hpp"]:::core
        CompilerCC["Compiler.cc"]:::core
        CompilerHPP["Compiler.hpp"]:::core
        BuildProfileHPP["BuildProfile.hpp"]:::core
    end

    %% Dependency Resolution
    subgraph "Dependency Resolution"
        direction TB
        subgraph "HTTP / GraphQL"
            direction TB
            CurlCC["CurlVersion.cc"]:::network
            CurlHPP["CurlVersion.hpp"]:::network
            GQL["SearchPackages.gql"]:::network
        end
        subgraph "Git Layer"
            direction TB
            Git2HPP["Git2.hpp"]:::vcs
            Git2Dir["Git2/"]:::vcs
        end
        subgraph "Versioning & Manifest"
            direction TB
            ManifestCC["Manifest.cc"]:::core
            ManifestHPP["Manifest.hpp"]:::core
            SemverCC["Semver.cc"]:::core
            SemverHPP["Semver.hpp"]:::core
            VersionReqCC["VersionReq.cc"]:::core
            VersionReqHPP["VersionReq.hpp"]:::core
            DependencyCC["Dependency.cc"]:::core
            DependencyHPP["Dependency.hpp"]:::core
        end
        subgraph "Orchestration & Parallelism"
            direction TB
            AlgosCC["Algos.cc"]:::core
            AlgosHPP["Algos.hpp"]:::core
            ParallelCC["Parallelism.cc"]:::core
            ParallelHPP["Parallelism.hpp"]:::core
        end
    end

    %% System Toolchain
    SystemCompiler["System C++ Compiler"]:::toolchain

    %% Filesystem & Config
    subgraph "Filesystem & Config"
        direction TB
        ManifestFile["cabin.toml"]:::fs
        TargetDir["target/"]:::fs
        CacheDir[".cabin_cache/"]:::fs
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Registry["Package Registry (GraphQL)"]:::external
        GitRemotes["Git Remotes"]:::external
    end

    %% Diagnostics & Logging
    Diag["Diag.hpp"]:::diag

    %% Tests
    Tests["tests/"]:::tests

    %% Connections
    User -->|"invokes cabin"| Main
    Main -->|"parses args"| CommandCC
    CommandCC -->|"dispatches to"| CmdAdd & CmdBuild & CmdInit & CmdRun
    CmdAdd & CmdBuild & CmdInit & CmdRun -->|"reads/writes"| ManifestFile
    CmdAdd & CmdBuild --> CoreBuildEngineEntry[/"Builder API"/]:::core
    CoreBuildEngineEntry --> BuildConfigCC & ProjectCC & CompilerCC & BuildProfileHPP
    CoreBuildEngineEntry --> CurlCC & Git2Dir & ManifestCC & AlgosCC & ParallelCC
    CurlCC -->|HTTP GraphQL queries| GQL
    GQL -->|to| Registry
    Git2Dir -->|clones/checkouts| GitRemotes
    ManifestCC -->|version consult| SemverCC & VersionReqCC & DependencyCC
    AlgosCC & ParallelCC -->|"build graph"| ProjectCC
    ProjectCC -->|invoke| CompilerCC
    CompilerCC -->|calls| SystemCompiler
    SystemCompiler -->|outputs artifacts to| TargetDir
    CoreBuildEngineEntry -->|cache| CacheDir
    Diag -->|logs| Main & CoreBuildEngineEntry
    Tests -->|shell scripts validate| User

    %% Click Events
    click Main "https://github.com/cabinpkg/cabin/blob/main/src/main.cc"
    click CliCC "https://github.com/cabinpkg/cabin/blob/main/src/Cli.cc"
    click CliHPP "https://github.com/cabinpkg/cabin/blob/main/src/Cli.hpp"
    click CommandCC "https://github.com/cabinpkg/cabin/blob/main/src/Command.cc"
    click CommandHPP "https://github.com/cabinpkg/cabin/blob/main/src/Command.hpp"
    click CmdAdd "https://github.com/cabinpkg/cabin/blob/main/src/Cmd/Add.cc"
    click CmdBuild "https://github.com/cabinpkg/cabin/blob/main/src/Cmd/Build.cc"
    click CmdInit "https://github.com/cabinpkg/cabin/blob/main/src/Cmd/Init.cc"
    click CmdRun "https://github.com/cabinpkg/cabin/blob/main/src/Cmd/Run.cc"
    click BuildConfigCC "https://github.com/cabinpkg/cabin/blob/main/src/BuildConfig.cc"
    click BuildConfigHPP "https://github.com/cabinpkg/cabin/blob/main/src/BuildConfig.hpp"
    click ProjectCC "https://github.com/cabinpkg/cabin/blob/main/src/Builder/Project.cc"
    click ProjectHPP "https://github.com/cabinpkg/cabin/blob/main/src/Builder/Project.hpp"
    click CompilerCC "https://github.com/cabinpkg/cabin/blob/main/src/Builder/Compiler.cc"
    click CompilerHPP "https://github.com/cabinpkg/cabin/blob/main/src/Builder/Compiler.hpp"
    click BuildProfileHPP "https://github.com/cabinpkg/cabin/blob/main/src/Builder/BuildProfile.hpp"
    click CurlCC "https://github.com/cabinpkg/cabin/blob/main/src/CurlVersion.cc"
    click CurlHPP "https://github.com/cabinpkg/cabin/blob/main/src/CurlVersion.hpp"
    click GQL "https://github.com/cabinpkg/cabin/blob/main/src/GraphQL/SearchPackages.gql"
    click Git2HPP "https://github.com/cabinpkg/cabin/blob/main/src/Git2.hpp"
    click Git2Dir "https://github.com/cabinpkg/cabin/tree/main/src/Git2/"
    click ManifestCC "https://github.com/cabinpkg/cabin/blob/main/src/Manifest.cc"
    click ManifestHPP "https://github.com/cabinpkg/cabin/blob/main/src/Manifest.hpp"
    click SemverCC "https://github.com/cabinpkg/cabin/blob/main/src/Semver.cc"
    click SemverHPP "https://github.com/cabinpkg/cabin/blob/main/src/Semver.hpp"
    click VersionReqCC "https://github.com/cabinpkg/cabin/blob/main/src/VersionReq.cc"
    click VersionReqHPP "https://github.com/cabinpkg/cabin/blob/main/src/VersionReq.hpp"
    click DependencyCC "https://github.com/cabinpkg/cabin/blob/main/src/Dependency.cc"
    click DependencyHPP "https://github.com/cabinpkg/cabin/blob/main/src/Dependency.hpp"
    click AlgosCC "https://github.com/cabinpkg/cabin/blob/main/src/Algos.cc"
    click AlgosHPP "https://github.com/cabinpkg/cabin/blob/main/src/Algos.hpp"
    click ParallelCC "https://github.com/cabinpkg/cabin/blob/main/src/Parallelism.cc"
    click ParallelHPP "https://github.com/cabinpkg/cabin/blob/main/src/Parallelism.hpp"
    click Diag "https://github.com/cabinpkg/cabin/blob/main/src/Diag.hpp"
    click Tests "https://github.com/cabinpkg/cabin/tree/main/tests/"

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px;
    classDef cli fill:#cce5ff,stroke:#1a73e8,stroke-width:1px;
    classDef core fill:#d1ecf1,stroke:#17a2b8,stroke-width:1px;
    classDef network fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef vcs fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef toolchain fill:#d1ecf1,stroke:#17a2b8,stroke-width:1px;
    classDef fs fill:#fff3cd,stroke:#ffc107,stroke-width:1px;
    classDef external fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef diag fill:#f8d7da,stroke:#dc3545,stroke-width:1px;
    classDef tests fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
```
