# novshi-tech/boid architecture

> Architecture diagram of the GitHub repository novshi-tech/boid, 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/novshi-tech/boid
- Repository: https://github.com/novshi-tech/boid

## Overview

boid is a local AI coding-agent orchestrator: a user creates and monitors tasks through the CLI or Web UI, while the daemon manages task state and runs agent work in isolated, write-scoped sandboxes. The main domain stages are task request, execution, verification/fix cycles, and completion; cards, scheduled triggers, projects, and workspace management provide related workflows. The graph highlights the API/orchestration/dispatch layers and the sandboxed agent runtime. README capabilities inform unsampled branches; detailed wiring is limited to the supplied excerpts and file tree.

Main entry points: [`internal/api/service.go`](https://github.com/novshi-tech/boid/blob/main/internal/api/service.go) (HTTP API), [`internal/sandbox/runner/runner.go`](https://github.com/novshi-tech/boid/blob/main/internal/sandbox/runner/runner.go) (Sandbox runtime), [`internal/api/task_service.go`](https://github.com/novshi-tech/boid/blob/main/internal/api/task_service.go) (Task services), [`internal/orchestrator/coordinator.go`](https://github.com/novshi-tech/boid/blob/main/internal/orchestrator/coordinator.go) (Lifecycle engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[root.go]"]
  node_webui["Web UI<br/>[web.go]"]
  node_client["Unix client<br/>[client.go]"]
end

subgraph group_daemon["Daemon services"]
  node_server["Daemon server<br/>[server.go]"]
  node_api["HTTP API<br/>[service.go]"]
  node_db[("SQLite state<br/>[db.go]")]
end

subgraph group_domain["Task domain"]
  node_taskapi["Task services<br/>[task_service.go]"]
  node_orchestrator["Lifecycle engine<br/>[coordinator.go]"]
  node_cards["Card workflows<br/>[card.go]"]
  node_triggers["Trigger scheduler<br/>[trigger_loop.go]"]
  node_projects["Projects<br/>[project_service.go]"]
  node_workspaces["Workspaces<br/>[workspace.go]"]
end

subgraph group_runtime["Agent runtime"]
  node_dispatcher["Job dispatcher<br/>[runner.go]"]
  node_sandbox["Sandbox runtime<br/>[runner.go]"]
  node_adapters["Agent adapters<br/>[registry.go]"]
  node_proxy["Egress controls<br/>[proxy_manager.go]"]
end

subgraph group_connectors["Gateways"]
  node_api_gateway["API gateway<br/>[server.go]"]
  node_git_gateway["Git gateway<br/>[server.go]"]
end

node_user(("Operator"))

node_user -->|"issues commands"| node_cli
node_user -->|"views and steers"| node_webui
node_cli -->|"sends requests"| node_client
node_client -->|"calls daemon"| node_server
node_webui -->|"uses web routes"| node_api
node_server -->|"serves routes"| node_api
node_api -->|"handles task requests"| node_taskapi
node_taskapi -->|"coordinates lifecycle"| node_orchestrator
node_orchestrator -->|"persists state"| node_db
node_taskapi -->|"reads and writes"| node_db
node_api -->|"dispatches card actions"| node_cards
node_api -->|"runs scheduled triggers"| node_triggers
node_api -->|"manages projects"| node_projects
node_api -->|"manages workspaces"| node_workspaces
node_orchestrator -->|"dispatches jobs"| node_dispatcher
node_dispatcher -->|"runs sandbox jobs"| node_sandbox
node_dispatcher -->|"invokes agent"| node_adapters
node_sandbox -->|"controls egress"| node_proxy
node_sandbox -.->|"routes API traffic"| node_api_gateway
node_sandbox -.->|"routes Git traffic"| node_git_gateway

click node_cli "https://github.com/novshi-tech/boid/blob/main/cmd/root.go"
click node_webui "https://github.com/novshi-tech/boid/blob/main/internal/api/web.go"
click node_client "https://github.com/novshi-tech/boid/blob/main/internal/client/client.go"
click node_server "https://github.com/novshi-tech/boid/blob/main/internal/server/server.go"
click node_api "https://github.com/novshi-tech/boid/blob/main/internal/api/service.go"
click node_db "https://github.com/novshi-tech/boid/blob/main/internal/db/db.go"
click node_taskapi "https://github.com/novshi-tech/boid/blob/main/internal/api/task_service.go"
click node_orchestrator "https://github.com/novshi-tech/boid/blob/main/internal/orchestrator/coordinator.go"
click node_cards "https://github.com/novshi-tech/boid/blob/main/internal/orchestrator/card.go"
click node_triggers "https://github.com/novshi-tech/boid/blob/main/internal/api/trigger_loop.go"
click node_projects "https://github.com/novshi-tech/boid/blob/main/internal/api/project_service.go"
click node_workspaces "https://github.com/novshi-tech/boid/blob/main/internal/api/workspace.go"
click node_dispatcher "https://github.com/novshi-tech/boid/blob/main/internal/dispatcher/runner.go"
click node_sandbox "https://github.com/novshi-tech/boid/blob/main/internal/sandbox/runner/runner.go"
click node_adapters "https://github.com/novshi-tech/boid/blob/main/internal/adapters/registry/registry.go"
click node_proxy "https://github.com/novshi-tech/boid/blob/main/internal/sandbox/proxy_manager.go"
click node_api_gateway "https://github.com/novshi-tech/boid/blob/main/internal/apigateway/server.go"
click node_git_gateway "https://github.com/novshi-tech/boid/blob/main/internal/gitgateway/server.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_cli,node_webui,node_client toneBlue
class node_server,node_api,node_db toneAmber
class node_taskapi,node_orchestrator,node_cards,node_triggers,node_projects,node_workspaces toneMint
class node_dispatcher,node_sandbox,node_adapters,node_proxy toneRose
class node_api_gateway,node_git_gateway,node_user toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/novshi-tech/boid/blob/main/cmd/root.go): `cmd/root.go`
- [Web UI](https://github.com/novshi-tech/boid/blob/main/internal/api/web.go): `internal/api/web.go`
- [Unix client](https://github.com/novshi-tech/boid/blob/main/internal/client/client.go): `internal/client/client.go`

### Daemon services

- [Daemon server](https://github.com/novshi-tech/boid/blob/main/internal/server/server.go): `internal/server/server.go`
- [HTTP API](https://github.com/novshi-tech/boid/blob/main/internal/api/service.go): `internal/api/service.go`
- [SQLite state](https://github.com/novshi-tech/boid/blob/main/internal/db/db.go): `internal/db/db.go`

### Task domain

- [Task services](https://github.com/novshi-tech/boid/blob/main/internal/api/task_service.go): `internal/api/task_service.go`
- [Lifecycle engine](https://github.com/novshi-tech/boid/blob/main/internal/orchestrator/coordinator.go): `internal/orchestrator/coordinator.go`
- [Card workflows](https://github.com/novshi-tech/boid/blob/main/internal/orchestrator/card.go): `internal/orchestrator/card.go`
- [Trigger scheduler](https://github.com/novshi-tech/boid/blob/main/internal/api/trigger_loop.go): `internal/api/trigger_loop.go`
- [Projects](https://github.com/novshi-tech/boid/blob/main/internal/api/project_service.go): `internal/api/project_service.go`
- [Workspaces](https://github.com/novshi-tech/boid/blob/main/internal/api/workspace.go): `internal/api/workspace.go`

### Agent runtime

- [Job dispatcher](https://github.com/novshi-tech/boid/blob/main/internal/dispatcher/runner.go): `internal/dispatcher/runner.go`
- [Sandbox runtime](https://github.com/novshi-tech/boid/blob/main/internal/sandbox/runner/runner.go): `internal/sandbox/runner/runner.go`
- [Agent adapters](https://github.com/novshi-tech/boid/blob/main/internal/adapters/registry/registry.go): `internal/adapters/registry/registry.go`
- [Egress controls](https://github.com/novshi-tech/boid/blob/main/internal/sandbox/proxy_manager.go): `internal/sandbox/proxy_manager.go`

### Gateways

- [API gateway](https://github.com/novshi-tech/boid/blob/main/internal/apigateway/server.go): `internal/apigateway/server.go`
- [Git gateway](https://github.com/novshi-tech/boid/blob/main/internal/gitgateway/server.go): `internal/gitgateway/server.go`

### Other components

- **Operator**

## Connections

- Operator → CLI commands: issues commands
- Operator → Web UI: views and steers
- CLI commands → Unix client: sends requests
- Unix client → Daemon server: calls daemon
- Web UI → HTTP API: uses web routes
- Daemon server → HTTP API: serves routes
- HTTP API → Task services: handles task requests
- Task services → Lifecycle engine: coordinates lifecycle
- Lifecycle engine → SQLite state: persists state
- Task services → SQLite state: reads and writes
- HTTP API → Card workflows: dispatches card actions
- HTTP API → Trigger scheduler: runs scheduled triggers
- HTTP API → Projects: manages projects
- HTTP API → Workspaces: manages workspaces
- Lifecycle engine → Job dispatcher: dispatches jobs
- Job dispatcher → Sandbox runtime: runs sandbox jobs
- Job dispatcher → Agent adapters: invokes agent
- Sandbox runtime → Egress controls: controls egress
- Sandbox runtime → API gateway: routes API traffic
- Sandbox runtime → Git gateway: routes Git traffic