# sbairoliya/buildbox architecture

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

- Interactive diagram: https://gitdiagram.com/sbairoliya/buildbox
- Repository: https://github.com/sbairoliya/buildbox

## Overview

##### Main Components
- Core Tools: Separate modules such as “recc”, “casd”, “casdownload”, “casupload”, “worker”, “run-oci”, “run-hosttools”, “run-bubblewrap”, “run-userchroot”, “fuse”, “rexplorer”, and “rumbad” are each standalone executable tools.
- Shared Libraries: Modules under directories like “common”, “commonmetrics”, and “cmake” provide shared utilities, configuration, and metric support.
- Protobuf & gRPC Interfaces: The “protos” directory contains the API definitions (for remote execution, content-addressable storage, etc.) which are central to communication between the tools and external services.
- Testing & Build Infrastructure: Numerous test directories and build scripts (e.g., “build-scripts”, “integration”, “docker-compose” files, and CI configurations) indicate a layered build/test/deployment setup.
- Documentation and Dev Tools: The “docs” and “clang-tidy” directories, along with Docker and devcontainer configuration files, highlight how code quality, containerization, and continuous integration are approached.

##### Relationships and Interactions
- Each tool (e.g., “recc” for remote compilation/configuration, “casd” for content-addressable storage delegation, “worker” for job execution) interacts with the external remote execution services via gRPC/protobuf messages defined in “protos.”
- The shared “common” and “commonmetrics” libraries serve as the foundation across tools, providing functionality like logging, metric collection, file operations, and connection setup.
- The build processes (via CMake, various Dockerfiles, and build scripts) indicate a multi-environment setup: local builds, containerized deployments, integration testing, and even platform-specific adjustments (Linux, Solaris).
- Network/data flow can also be illustrated for how the build actions and caching operations circulate through modules: e.g., client components bundling commands in “recc” sending requests to “worker” instances, which in turn interact with a remote execution service.

##### Architectural Patterns and Design Principles
- Modularity and Separation of Concerns: Each sub-directory and component is logically isolated (for instance, separate directories for downloading (“casdownload”) vs. uploading (“casupload”)).
- Reusability through Shared Libraries: “common” and “commonmetrics” are reused across tools ensuring consistency and reducing duplication.
- Client-Server and Microservice Patterns: Some components (like “worker”) are designed as independent executables able to communicate through well-defined gRPC interfaces, aligning with microservice architecture principles.
- Containerization & CI/CD: Use of Dockerfiles, devcontainer setup, and GitLab CI configuration emphasizes automated deployment/testing processes.

##### Relevant Technologies and Frameworks
- Build and Dependency Tools: CMake, Ninja, GNU Make.
- Networking and Serialization: gRPC, Protobuf.
- Testing Frameworks: GoogleTest and GoogleBenchmark.
- Logging & Metrics: glog and custom metrics modules under “commonmetrics.”
- Containerization: Docker-related configurations and Docker Compose files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Remote Execution Tools
    subgraph "Remote Execution Tools"
        recc["recc – Remote Execution Client"]
        worker["worker – Execution Daemon"]
    end

    %% Content Addressable Services
    subgraph "Content Addressable Services"
        casd["casd – CAS Delegation"]
        casdownload["casdownload – CAS Download"]
        casupload["casupload – CAS Upload"]
    end

    %% Other Core Tools
    subgraph "Other Core Tools"
        runoci["run-oci – OCI Runner"]
        runhosttools["run-hosttools – Host Tools Runner"]
        runbubblewrap["run-bubblewrap – Bubblewrap Runner"]
        runuserchroot["run-userchroot – UserChroot Runner"]
        fuse["fuse – FUSE Interface"]
        rexplorer["rexplorer – Remote Explorer"]
        rumbad["rumbad – Remote Build Analyzer"]
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        common["common – Utility Library"]
        commonmetrics["commonmetrics – Metrics Library"]
        cmake["cmake – Build Configuration"]
    end

    %% Protobuf & gRPC Interfaces
    subgraph "Protobuf & gRPC Interfaces"
        protos["protos – API Definitions"]
    end

    %% Testing & Build Infrastructure
    subgraph "Testing & Build Infrastructure"
        buildscripts["build-scripts – Build Scripts"]
        dockercompose["docker-compose – CI/CD & Docker Config"]
    end

    %% Documentation & Dev Tools
    subgraph "Documentation & Dev Tools"
        docs["docs – Documentation"]
        clangtidy["clang-tidy – Coding Tools"]
    end

    %% External System
    external["Remote Execution API Endpoint"]

    %% Connections between Components
    recc -->|"sends_request"| worker
    recc -->|"uses_grpc"| protos
    worker -->|"communicates"| protos

    casd -->|"cas_comm"| protos
    casdownload -->|"cas_comm"| protos
    casupload -->|"cas_comm"| protos

    runoci -->|"uses_grpc"| protos
    runhosttools -->|"uses_grpc"| protos
    runbubblewrap -->|"uses_grpc"| protos
    runuserchroot -->|"uses_grpc"| protos
    fuse -->|"uses_rpc"| protos
    rexplorer -->|"queries"| protos
    rumbad -->|"analyzes"| protos

    worker -->|"executes_remote_build"| external

    %% Shared Libraries usage connections
    recc -->|"utilizes"| common
    worker -->|"utilizes"| common
    runoci -->|"utilizes"| common
    worker -->|"metrics"| commonmetrics

    %% Build Infrastructure connections
    buildscripts -->|"configures"| cmake
    buildscripts -->|"orchestrates"| protos
    dockercompose -->|"deploys"| worker

    %% Class Definitions for Colors
    classDef tool fill:#FFCC00,stroke:#333,stroke-width:2px,color:black;
    classDef library fill:#8FBC8F,stroke:#333,stroke-width:2px,color:black;
    classDef proto fill:#ADD8E6,stroke:#333,stroke-width:2px,color:black;
    classDef infra fill:#FFA07A,stroke:#333,stroke-width:2px,color:black;
    classDef doc fill:#DDA0DD,stroke:#333,stroke-width:2px,color:black;
    classDef external fill:#F4A460,stroke:#333,stroke-width:2px,color:black;

    %% Assigning Classes
    class recc,worker,casd,casdownload,casupload,runoci,runhosttools,runbubblewrap,runuserchroot,fuse,rexplorer,rumbad tool;
    class common,commonmetrics,cmake library;
    class protos proto;
    class buildscripts,dockercompose infra;
    class docs,clangtidy doc;
    class external external;

    %% Click Events for Components
    click recc "https://github.com/sbairoliya/buildbox/tree/main/recc"
    click casd "https://github.com/sbairoliya/buildbox/tree/main/casd"
    click casdownload "https://github.com/sbairoliya/buildbox/tree/main/casdownload"
    click casupload "https://github.com/sbairoliya/buildbox/tree/main/casupload"
    click worker "https://github.com/sbairoliya/buildbox/tree/main/worker"
    click runoci "https://github.com/sbairoliya/buildbox/tree/main/run-oci"
    click runhosttools "https://github.com/sbairoliya/buildbox/tree/main/run-hosttools"
    click runbubblewrap "https://github.com/sbairoliya/buildbox/tree/main/run-bubblewrap"
    click runuserchroot "https://github.com/sbairoliya/buildbox/tree/main/run-userchroot"
    click fuse "https://github.com/sbairoliya/buildbox/tree/main/fuse"
    click rexplorer "https://github.com/sbairoliya/buildbox/tree/main/rexplorer"
    click rumbad "https://github.com/sbairoliya/buildbox/tree/main/rumbad"
    click common "https://github.com/sbairoliya/buildbox/tree/main/common"
    click commonmetrics "https://github.com/sbairoliya/buildbox/tree/main/commonmetrics"
    click cmake "https://github.com/sbairoliya/buildbox/tree/main/cmake"
    click protos "https://github.com/sbairoliya/buildbox/tree/main/protos"
    click buildscripts "https://github.com/sbairoliya/buildbox/tree/main/build-scripts"
    click dockercompose "https://github.com/sbairoliya/buildbox/blob/main/docker-compose.casd.yml"
    click docs "https://github.com/sbairoliya/buildbox/tree/main/docs"
    click clangtidy "https://github.com/sbairoliya/buildbox/tree/main/clang-tidy"
```
