# buildbarn/bonanza architecture

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

- Interactive diagram: https://gitdiagram.com/buildbarn/bonanza
- Repository: https://github.com/buildbarn/bonanza
- Video tour (about a minute): https://gitdiagram.com/buildbarn/bonanza/video

## Overview

Bonanza is an experimental Bazel-compatible remote build system. Its principal workflow is to submit local source and a build request, perform build analysis remotely, fetch required dependencies, schedule and execute actions on workers, then expose progress and results. The tree shows dedicated services and model packages for these stages; the README documents the overall workflow and compatibility goals. Source excerpts are limited, so internal service-to-service edges are shown only where supported by the documented architecture or sampled worker setup.

Main entry points: [`cmd/bonanza_builder/main.go`](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_builder/main.go) (Build service), [`cmd/bonanza_worker/main.go`](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_worker/main.go) (Execution worker), [`cmd/bonanza_bazel/main.go`](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_bazel/main.go) (Bazel-compatible CLI), [`pkg/model/analysis`](https://github.com/buildbarn/bonanza/tree/main/pkg/model/analysis) (Build analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and UI"]
  node_bazelcli["Bazel-compatible CLI<br/>[main.go]"]
  node_browser["Build browser<br/>[main.go]"]
  node_progress["Build status"]
end

subgraph group_build["Build processing"]
  node_builder["Build service<br/>[main.go]"]
  node_analysis["Build analysis"]
  node_starlark["Bazel Starlark"]
  node_evaluation["Dependency evaluation"]
  node_fetcher["Repository fetcher<br/>[main.go]"]
  node_fetchmodel["Fetch model"]
end

subgraph group_execution["Remote execution"]
  node_scheduler["Build scheduler<br/>[main.go]"]
  node_routing["Action routing"]
  node_worker["Execution worker<br/>[main.go]"]
  node_remote["Worker protocol"]
  node_buildermodel["Storage-backed execution"]
end

subgraph group_storage["Object storage"]
  node_storagefrontend["Storage frontend<br/>[main.go]"]
  node_shard["Storage shard<br/>[main.go]"]
  node_dag["DAG storage"]
  node_objectstore[("Object store")]
  node_tagstore[("Tag storage")]
end

node_user(("Developer or caller"))

node_user -->|"invokes"| node_bazelcli
node_user -.->|"views builds"| node_browser
node_bazelcli -->|"uploads source"| node_storagefrontend
node_bazelcli -->|"requests build"| node_builder
node_builder -->|"analyzes targets"| node_analysis
node_analysis -->|"evaluates rules"| node_starlark
node_analysis -->|"evaluates dependencies"| node_evaluation
node_evaluation -->|"requests repositories"| node_fetcher
node_fetcher -->|"fetches inputs"| node_fetchmodel
node_builder -->|"schedules actions"| node_scheduler
node_scheduler -->|"routes actions"| node_routing
node_scheduler -->|"dispatches work"| node_worker
node_worker -->|"serves execution"| node_remote
node_worker -->|"loads stored actions"| node_buildermodel
node_worker -->|"uploads results"| node_storagefrontend
node_builder -->|"reports status"| node_progress
node_browser -->|"reads status"| node_progress
node_storagefrontend -->|"forwards storage requests"| node_shard
node_shard -->|"stores DAGs"| node_dag
node_dag -->|"reads and writes objects"| node_objectstore
node_shard -->|"stores tags"| node_tagstore

click node_bazelcli "https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_bazel/main.go"
click node_browser "https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_browser/main.go"
click node_builder "https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_builder/main.go"
click node_analysis "https://github.com/buildbarn/bonanza/tree/main/pkg/model/analysis"
click node_starlark "https://github.com/buildbarn/bonanza/tree/main/pkg/model/starlark"
click node_evaluation "https://github.com/buildbarn/bonanza/tree/main/pkg/model/evaluation"
click node_fetcher "https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_fetcher/main.go"
click node_fetchmodel "https://github.com/buildbarn/bonanza/tree/main/pkg/model/fetch"
click node_scheduler "https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_scheduler/main.go"
click node_routing "https://github.com/buildbarn/bonanza/tree/main/pkg/scheduler/routing"
click node_worker "https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_worker/main.go"
click node_remote "https://github.com/buildbarn/bonanza/tree/main/pkg/remoteworker"
click node_buildermodel "https://github.com/buildbarn/bonanza/tree/main/pkg/model/executewithstorage"
click node_storagefrontend "https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_storage_frontend/main.go"
click node_shard "https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_storage_shard/main.go"
click node_dag "https://github.com/buildbarn/bonanza/tree/main/pkg/storage/dag"
click node_objectstore "https://github.com/buildbarn/bonanza/tree/main/pkg/storage/object"
click node_tagstore "https://github.com/buildbarn/bonanza/tree/main/pkg/storage/tag"
click node_progress "https://github.com/buildbarn/bonanza/blob/main/pkg/proto/buildqueuestate/buildqueuestate.proto"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bazelcli,node_browser,node_progress toneBlue
class node_builder,node_analysis,node_starlark,node_evaluation,node_fetcher,node_fetchmodel toneAmber
class node_scheduler,node_routing,node_worker,node_remote,node_buildermodel toneMint
class node_storagefrontend,node_shard,node_dag,node_objectstore,node_tagstore toneRose
class node_user toneIndigo
```

## Components

### Client and UI

- [Bazel-compatible CLI](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_bazel/main.go): `cmd/bonanza_bazel/main.go`
- [Build browser](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_browser/main.go): `cmd/bonanza_browser/main.go`
- [Build status](https://github.com/buildbarn/bonanza/blob/main/pkg/proto/buildqueuestate/buildqueuestate.proto): `pkg/proto/buildqueuestate/buildqueuestate.proto`

### Build processing

- [Build service](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_builder/main.go): `cmd/bonanza_builder/main.go`
- [Build analysis](https://github.com/buildbarn/bonanza/tree/main/pkg/model/analysis): `pkg/model/analysis`
- [Bazel Starlark](https://github.com/buildbarn/bonanza/tree/main/pkg/model/starlark): `pkg/model/starlark`
- [Dependency evaluation](https://github.com/buildbarn/bonanza/tree/main/pkg/model/evaluation): `pkg/model/evaluation`
- [Repository fetcher](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_fetcher/main.go): `cmd/bonanza_fetcher/main.go`
- [Fetch model](https://github.com/buildbarn/bonanza/tree/main/pkg/model/fetch): `pkg/model/fetch`

### Remote execution

- [Build scheduler](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_scheduler/main.go): `cmd/bonanza_scheduler/main.go`
- [Action routing](https://github.com/buildbarn/bonanza/tree/main/pkg/scheduler/routing): `pkg/scheduler/routing`
- [Execution worker](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_worker/main.go): `cmd/bonanza_worker/main.go`
- [Worker protocol](https://github.com/buildbarn/bonanza/tree/main/pkg/remoteworker): `pkg/remoteworker`
- [Storage-backed execution](https://github.com/buildbarn/bonanza/tree/main/pkg/model/executewithstorage): `pkg/model/executewithstorage`

### Object storage

- [Storage frontend](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_storage_frontend/main.go): `cmd/bonanza_storage_frontend/main.go`
- [Storage shard](https://github.com/buildbarn/bonanza/blob/main/cmd/bonanza_storage_shard/main.go): `cmd/bonanza_storage_shard/main.go`
- [DAG storage](https://github.com/buildbarn/bonanza/tree/main/pkg/storage/dag): `pkg/storage/dag`
- [Object store](https://github.com/buildbarn/bonanza/tree/main/pkg/storage/object): `pkg/storage/object`
- [Tag storage](https://github.com/buildbarn/bonanza/tree/main/pkg/storage/tag): `pkg/storage/tag`

### Other components

- **Developer or caller**

## Connections

- Developer or caller → Bazel-compatible CLI: invokes
- Developer or caller → Build browser: views builds
- Bazel-compatible CLI → Storage frontend: uploads source
- Bazel-compatible CLI → Build service: requests build
- Build service → Build analysis: analyzes targets
- Build analysis → Bazel Starlark: evaluates rules
- Build analysis → Dependency evaluation: evaluates dependencies
- Dependency evaluation → Repository fetcher: requests repositories
- Repository fetcher → Fetch model: fetches inputs
- Build service → Build scheduler: schedules actions
- Build scheduler → Action routing: routes actions
- Build scheduler → Execution worker: dispatches work
- Execution worker → Worker protocol: serves execution
- Execution worker → Storage-backed execution: loads stored actions
- Execution worker → Storage frontend: uploads results
- Build service → Build status: reports status
- Build browser → Build status: reads status
- Storage frontend → Storage shard: forwards storage requests
- Storage shard → DAG storage: stores DAGs
- DAG storage → Object store: reads and writes objects
- Storage shard → Tag storage: stores tags