# block/builderbot architecture

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

- Interactive diagram: https://gitdiagram.com/block/builderbot
- Repository: https://github.com/block/builderbot

## Overview

Builderbot is a monorepo of desktop developer tools: Staged manages projects, branches, agent sessions and Git/PR pipelines; Differ presents repository diffs and review context; Penpal provides a project/file review interface and server. The main Staged workflow runs from the desktop shell through project/branch operations into queued session work, with results persisted and exposed to the UI. Differ and Penpal are separate product branches. The graph follows documented app scope and indexed source references; unsampled implementation details and unshown runtime wiring are intentionally not inferred.

Main entry points: [`apps/staged/src-tauri/src/prs/pipeline.rs`](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/pipeline.rs) (Pipeline Sessions), [`apps/staged/src-tauri/src/store/mod.rs`](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/store/mod.rs) (SQLite Store), [`apps/staged/src-tauri/src/session_queue/kick.rs`](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/session_queue/kick.rs) (Session Queue), [`apps/penpal/internal/server/server.go`](https://github.com/block/builderbot/blob/main/apps/penpal/internal/server/server.go) (Penpal Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_staged["Staged Desktop"]
  node_staged_ui["Staged Shell<br/>[App.svelte]"]
  node_transport["UI Transport<br/>[transport.ts]"]
  node_pipeline_steps_ui["Pipeline Progress"]
end

subgraph group_staged_core["Staged Runtime"]
  node_branch_ops["Branch Operations<br/>[branches.rs]"]
  node_session_cmds["Session Commands"]
  node_session_runner["Session Runner<br/>[session_runner.rs]"]
  node_session_queue["Session Queue<br/>[kick.rs]"]
  node_pipeline["Pipeline Sessions<br/>[pipeline.rs]"]
  node_pipeline_context["Branch Context<br/>[context.rs]"]
  node_git_pipeline["Git Pipelines<br/>[git_pipeline.rs]"]
  node_push_pipeline["Push Pipeline<br/>[push.rs]"]
  node_commit_pipeline["Commit Pipeline<br/>[commit.rs]"]
  node_pipeline_gate["Pipeline Gates"]
  node_staged_store[("SQLite Store<br/>[mod.rs]")]
  node_web_server["Web Server<br/>[web_server.rs]"]
end

subgraph group_differ["Differ"]
  node_differ_ui["Diff Workspace<br/>[App.svelte]"]
  node_differ_commands["Native Commands<br/>[commands.ts]"]
  node_differ_preferences["Preferences"]
end

subgraph group_penpal["Penpal"]
  node_penpal_cli["Penpal CLI<br/>[main.go]"]
  node_penpal_server["Penpal Server<br/>[server.go]"]
  node_penpal_ui["Review UI<br/>[App.tsx]"]
  node_penpal_manager["Agent Manager<br/>[manager.go]"]
  node_penpal_comments[("Comment Storage<br/>[storage.go]")]
end

node_user(("Developer"))

node_user -->|"uses"| node_staged_ui
node_staged_ui -->|"calls"| node_transport
node_transport -.->|"communicates with"| node_web_server
node_web_server -->|"routes to"| node_branch_ops
node_branch_ops -->|"reads and writes"| node_staged_store
node_branch_ops -->|"dispatches"| node_session_queue
node_session_cmds -->|"starts"| node_session_runner
node_session_queue -->|"starts queued work"| node_session_runner
node_session_queue -->|"reads and writes"| node_staged_store
node_pipeline -->|"persists session"| node_staged_store
node_pipeline -->|"resolves context"| node_pipeline_context
node_git_pipeline -->|"starts pipeline"| node_pipeline
node_git_pipeline -->|"resolves branch"| node_pipeline_context
node_push_pipeline -->|"queues work"| node_pipeline
node_push_pipeline -->|"rebuilds queued work"| node_git_pipeline
node_commit_pipeline -->|"shares session plumbing"| node_pipeline
node_pipeline_gate -->|"checks dependency"| node_staged_store
node_pipeline -->|"queues sessions"| node_session_queue
node_session_runner -.->|"updates state"| node_staged_store
node_pipeline_steps_ui -->|"subscribes to events"| node_transport
node_user -->|"uses"| node_differ_ui
node_differ_ui -->|"calls"| node_differ_commands
node_differ_ui -->|"initializes"| node_differ_preferences
node_user -->|"uses"| node_penpal_ui
node_penpal_ui -.->|"requests data"| node_penpal_server
node_penpal_cli -.->|"starts server"| node_penpal_server
node_penpal_server -.->|"uses agents"| node_penpal_manager
node_penpal_server -.->|"stores comments"| node_penpal_comments

click node_staged_ui "https://github.com/block/builderbot/blob/main/apps/staged/src/App.svelte"
click node_transport "https://github.com/block/builderbot/blob/main/apps/staged/src/lib/transport.ts"
click node_branch_ops "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/branches.rs"
click node_session_cmds "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/session_commands.rs"
click node_session_runner "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/session_runner.rs"
click node_session_queue "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/session_queue/kick.rs"
click node_pipeline "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/pipeline.rs"
click node_pipeline_context "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/context.rs"
click node_git_pipeline "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/git_pipeline.rs"
click node_push_pipeline "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/push.rs"
click node_commit_pipeline "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/commit.rs"
click node_pipeline_gate "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/pipeline_dependency.rs"
click node_staged_store "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/store/mod.rs"
click node_web_server "https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/web_server.rs"
click node_pipeline_steps_ui "https://github.com/block/builderbot/blob/main/apps/staged/src/lib/features/sessions/PipelineSteps.svelte"
click node_differ_ui "https://github.com/block/builderbot/blob/main/apps/differ/src/App.svelte"
click node_differ_commands "https://github.com/block/builderbot/blob/main/apps/differ/src/lib/commands.ts"
click node_differ_preferences "https://github.com/block/builderbot/blob/main/apps/differ/src/lib/preferences.svelte.ts"
click node_penpal_cli "https://github.com/block/builderbot/blob/main/apps/penpal/cmd/penpal-cli/main.go"
click node_penpal_server "https://github.com/block/builderbot/blob/main/apps/penpal/internal/server/server.go"
click node_penpal_ui "https://github.com/block/builderbot/blob/main/apps/penpal/frontend/src/App.tsx"
click node_penpal_manager "https://github.com/block/builderbot/blob/main/apps/penpal/internal/agents/manager.go"
click node_penpal_comments "https://github.com/block/builderbot/blob/main/apps/penpal/internal/comments/storage.go"

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_staged_ui,node_transport,node_pipeline_steps_ui toneBlue
class node_branch_ops,node_session_cmds,node_session_runner,node_session_queue,node_pipeline,node_pipeline_context,node_git_pipeline,node_push_pipeline,node_commit_pipeline,node_pipeline_gate,node_staged_store,node_web_server toneAmber
class node_differ_ui,node_differ_commands,node_differ_preferences toneMint
class node_penpal_cli,node_penpal_server,node_penpal_ui,node_penpal_manager,node_penpal_comments toneRose
class node_user toneIndigo
```

## Components

### Staged Desktop

- [Staged Shell](https://github.com/block/builderbot/blob/main/apps/staged/src/App.svelte): `apps/staged/src/App.svelte`
- [UI Transport](https://github.com/block/builderbot/blob/main/apps/staged/src/lib/transport.ts): `apps/staged/src/lib/transport.ts`
- [Pipeline Progress](https://github.com/block/builderbot/blob/main/apps/staged/src/lib/features/sessions/PipelineSteps.svelte): `apps/staged/src/lib/features/sessions/PipelineSteps.svelte`

### Staged Runtime

- [Branch Operations](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/branches.rs): `apps/staged/src-tauri/src/branches.rs`
- [Session Commands](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/session_commands.rs): `apps/staged/src-tauri/src/session_commands.rs`
- [Session Runner](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/session_runner.rs): `apps/staged/src-tauri/src/session_runner.rs`
- [Session Queue](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/session_queue/kick.rs): `apps/staged/src-tauri/src/session_queue/kick.rs`
- [Pipeline Sessions](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/pipeline.rs): `apps/staged/src-tauri/src/prs/pipeline.rs`
- [Branch Context](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/context.rs): `apps/staged/src-tauri/src/prs/context.rs`
- [Git Pipelines](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/git_pipeline.rs): `apps/staged/src-tauri/src/prs/git_pipeline.rs`
- [Push Pipeline](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/push.rs): `apps/staged/src-tauri/src/prs/push.rs`
- [Commit Pipeline](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/prs/commit.rs): `apps/staged/src-tauri/src/prs/commit.rs`
- [Pipeline Gates](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/pipeline_dependency.rs): `apps/staged/src-tauri/src/pipeline_dependency.rs`
- [SQLite Store](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/store/mod.rs): `apps/staged/src-tauri/src/store/mod.rs`
- [Web Server](https://github.com/block/builderbot/blob/main/apps/staged/src-tauri/src/web_server.rs): `apps/staged/src-tauri/src/web_server.rs`

### Differ

- [Diff Workspace](https://github.com/block/builderbot/blob/main/apps/differ/src/App.svelte): `apps/differ/src/App.svelte`
- [Native Commands](https://github.com/block/builderbot/blob/main/apps/differ/src/lib/commands.ts): `apps/differ/src/lib/commands.ts`
- [Preferences](https://github.com/block/builderbot/blob/main/apps/differ/src/lib/preferences.svelte.ts): `apps/differ/src/lib/preferences.svelte.ts`

### Penpal

- [Penpal CLI](https://github.com/block/builderbot/blob/main/apps/penpal/cmd/penpal-cli/main.go): `apps/penpal/cmd/penpal-cli/main.go`
- [Penpal Server](https://github.com/block/builderbot/blob/main/apps/penpal/internal/server/server.go): `apps/penpal/internal/server/server.go`
- [Review UI](https://github.com/block/builderbot/blob/main/apps/penpal/frontend/src/App.tsx): `apps/penpal/frontend/src/App.tsx`
- [Agent Manager](https://github.com/block/builderbot/blob/main/apps/penpal/internal/agents/manager.go): `apps/penpal/internal/agents/manager.go`
- [Comment Storage](https://github.com/block/builderbot/blob/main/apps/penpal/internal/comments/storage.go): `apps/penpal/internal/comments/storage.go`

### Other components

- **Developer**

## Connections

- Developer → Staged Shell: uses (evidence: `README.md`)
- Staged Shell → UI Transport: calls (evidence: `apps/staged/src/App.svelte`)
- UI Transport → Web Server: communicates with
- Web Server → Branch Operations: routes to (evidence: `apps/staged/src-tauri/src/branches.rs`)
- Branch Operations → SQLite Store: reads and writes (evidence: `apps/staged/src-tauri/src/branches.rs`)
- Branch Operations → Session Queue: dispatches (evidence: `apps/staged/src-tauri/src/branches.rs`)
- Session Commands → Session Runner: starts
- Session Queue → Session Runner: starts queued work
- Session Queue → SQLite Store: reads and writes
- Pipeline Sessions → SQLite Store: persists session (evidence: `apps/staged/src-tauri/src/prs/pipeline.rs`)
- Pipeline Sessions → Branch Context: resolves context (evidence: `apps/staged/src-tauri/src/prs/pipeline.rs`)
- Git Pipelines → Pipeline Sessions: starts pipeline (evidence: `apps/staged/src-tauri/src/prs/git_pipeline.rs`)
- Git Pipelines → Branch Context: resolves branch (evidence: `apps/staged/src-tauri/src/prs/git_pipeline.rs`)
- Push Pipeline → Pipeline Sessions: queues work (evidence: `apps/staged/src-tauri/src/prs/push.rs`)
- Push Pipeline → Git Pipelines: rebuilds queued work (evidence: `apps/staged/src-tauri/src/prs/push.rs`)
- Commit Pipeline → Pipeline Sessions: shares session plumbing (evidence: `apps/staged/src-tauri/src/prs/pipeline.rs`)
- Pipeline Gates → SQLite Store: checks dependency (evidence: `apps/staged/src-tauri/src/pipeline_dependency.rs`)
- Pipeline Sessions → Session Queue: queues sessions (evidence: `apps/staged/src-tauri/src/prs/pipeline.rs`)
- Session Runner → SQLite Store: updates state
- Pipeline Progress → UI Transport: subscribes to events (evidence: `apps/staged/src/lib/features/sessions/PipelineSteps.svelte`)
- Developer → Diff Workspace: uses (evidence: `README.md`)
- Diff Workspace → Native Commands: calls (evidence: `apps/differ/src/App.svelte`)
- Diff Workspace → Preferences: initializes (evidence: `apps/differ/src/App.svelte`)
- Developer → Review UI: uses (evidence: `apps/penpal/frontend/src/App.tsx`)
- Review UI → Penpal Server: requests data
- Penpal CLI → Penpal Server: starts server
- Penpal Server → Agent Manager: uses agents
- Penpal Server → Comment Storage: stores comments
