# oxidecomputer/buildomat architecture

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

- Interactive diagram: https://gitdiagram.com/oxidecomputer/buildomat
- Repository: https://github.com/oxidecomputer/buildomat

## Overview

##### Main Components Overview

a. Core Components:
- Buildomat Server (Central API Server)
- Client Components (CLI & Library)
- Agent System
- Database Layer

b. Factory Systems:
- AWS Factory
- Lab Factory

c. GitHub Integration:
- GitHub Server
- GitHub Database
- Webhook Processing System

##### Component Relationships

a. Control Flow:
- GitHub webhooks → GitHub Integration Server
- GitHub Integration Server → Core Server
- Client Tools → Core Server
- Factories → Core Server
- Agents → Core Server

b. Data Flow:
- Core Server ↔ Database
- GitHub Integration ↔ GitHub Database
- Build Artifacts Flow (Agent → Server → Storage)

##### Specific Implementation Details

Technical elements:

a. Server Components:
**[GitHub Webhooks] → [GitHub Integration Server]**
- ↓
**[Core API Server] ← → [Database]**
- ↑     ↑

**[Factories] [Agents]**

b. Factory Implementation:
**[Factory Manager]**
- ↓
**[Resource Provisioning]**
- ↓
**[Worker Management]**

##### Detailed Component Breakdown

For each major component, show:

a. Server:
- API endpoints
- Job management
- Worker coordination
- File management

b. Factories:
- Resource provisioning
- Instance lifecycle
- Worker coordination

c. Agent:
- Job execution
- File transfer
- Security components

##### Cross-Cutting Concerns

Aspects:

- Authentication flows
- Security boundaries
- Monitoring points
- Scaling components

##### The security boundaries between components

Remember to highlight the ephemeral nature of workers and the job execution lifecycle, as these are central to the system's design philosophy.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External
        GHW[GitHub Webhooks]
    end

    subgraph "GitHub Integration"
        GIS["GitHub Server"]:::github
        GDB[(GitHub Database)]:::database
        WHT["Webhook Types"]:::github
    end

    subgraph "Core System"
        CAS["Core API Server"]:::core
        DB[(Database)]:::database
        JM["Job Management"]:::core
        WC["Worker Coordination"]:::core
        API["API Endpoints"]:::core
    end

    subgraph "Client Layer"
        CLI["Client Library"]:::client
        EVT["Events System"]:::client
    end

    subgraph "Agent System"
        AGT["Main Agent"]:::agent
        CP["Control Protocol"]:::agent
        EX["Execution"]:::agent
        FU["File Upload"]:::agent
        FD["File Download"]:::agent
    end

    subgraph "Factory Systems"
        subgraph "AWS Factory"
            AWSC["AWS Configuration"]:::factory
            AWSI["AWS Implementation"]:::factory
        end

        subgraph "Lab Factory"
            LWM["Worker Management"]:::factory
            LC["Lab Configuration"]:::factory
        end
    end

    subgraph "Common Components"
        TD["Type Definitions"]:::common
        CU["Common Utilities"]:::common
        DS["Download System"]:::common
    end

    %% Relationships
    GHW --> GIS
    GIS <--> GDB
    GIS --> WHT
    GIS --> CAS

    CAS <--> DB
    CAS --> JM
    CAS --> WC
    CAS --> API

    CLI --> CAS
    CLI --> EVT

    AGT --> CAS
    AGT --> CP
    AGT --> EX
    AGT --> FU
    AGT --> FD

    AWSC --> CAS
    AWSI --> CAS
    LWM --> CAS
    LC --> CAS

    %% Click events
    click CAS "https://github.com/oxidecomputer/buildomat/tree/main/server"
    click API "https://github.com/oxidecomputer/buildomat/tree/main/server/src/api"
    click JM "https://github.com/oxidecomputer/buildomat/blob/main/server/src/jobs.rs"
    click WC "https://github.com/oxidecomputer/buildomat/blob/main/server/src/workers.rs"
    click DB "https://github.com/oxidecomputer/buildomat/blob/main/server/schema.sql"
    click CLI "https://github.com/oxidecomputer/buildomat/blob/main/client/src/lib.rs"
    click EVT "https://github.com/oxidecomputer/buildomat/blob/main/client/src/events.rs"
    click AGT "https://github.com/oxidecomputer/buildomat/blob/main/agent/src/main.rs"
    click CP "https://github.com/oxidecomputer/buildomat/blob/main/agent/src/control/protocol.rs"
    click EX "https://github.com/oxidecomputer/buildomat/blob/main/agent/src/exec.rs"
    click FU "https://github.com/oxidecomputer/buildomat/blob/main/agent/src/upload.rs"
    click FD "https://github.com/oxidecomputer/buildomat/blob/main/agent/src/download.rs"
    click AWSC "https://github.com/oxidecomputer/buildomat/blob/main/factory/aws/src/config.rs"
    click AWSI "https://github.com/oxidecomputer/buildomat/blob/main/factory/aws/src/aws.rs"
    click LWM "https://github.com/oxidecomputer/buildomat/blob/main/factory/lab/src/worker.rs"
    click LC "https://github.com/oxidecomputer/buildomat/blob/main/factory/lab/src/config.rs"
    click GIS "https://github.com/oxidecomputer/buildomat/tree/main/github/server"
    click GDB "https://github.com/oxidecomputer/buildomat/blob/main/github/database/schema.sql"
    click WHT "https://github.com/oxidecomputer/buildomat/blob/main/github/hooktypes/src/lib.rs"
    click TD "https://github.com/oxidecomputer/buildomat/blob/main/types/src/lib.rs"
    click CU "https://github.com/oxidecomputer/buildomat/blob/main/common/src/lib.rs"
    click DS "https://github.com/oxidecomputer/buildomat/blob/main/download/src/lib.rs"

    %% Styling
    classDef core fill:#2374ab
    classDef database fill:#2a9d8f
    classDef client fill:#e9c46a
    classDef agent fill:#f4a261
    classDef factory fill:#e76f51
    classDef github fill:#264653
    classDef common fill:#8338ec

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[(Database)]:::database
        L3[Client Components]:::client
        L4[Agent Components]:::agent
        L5[Factory Components]:::factory
        L6[GitHub Components]:::github
        L7[Common Components]:::common
    end
```
