Architecture Overview

Toban has three main components that work together:

Browser                         Your Machine
+-----------------+             +------------------+
|   Dashboard     |  WebSocket  |   Toban CLI      |
|   (toban.dev)   | <---------> |   (toban-cli)    |
|                 |             |                  |
|  Sprint Board   |             |  Manager Agent   |
|  Chat Panel     |             |  Builder Agents  |
|  Terminal View  |             |  Git Operations  |
|  Review Flow    |             |                  |
+-----------------+             +------------------+
        |                               |
        |  REST API                     |  Git Push
        v                               v
+-----------------+             +------------------+
|   Toban API     |             |   GitHub         |
|   (Cloudflare)  |             |   Repositories   |
|                 |             +------------------+
|  Quality Scores |
|  Failure DB     |
|  Knowledge      |
+-----------------+

Dashboard

The web interface where you manage sprints, review agent work, and chat with the Manager.

• Sprint Board -- Kanban-style task management with drag-and-drop
• Chat Panel -- Talk to the Manager agent to plan sprints, propose tasks, and coordinate
• Terminal Panel -- See what agents are doing in real-time (file reads, edits, commands)
• Review Flow -- Approve or reject completed work with one click

Toban CLI

Runs on your machine and orchestrates the AI agents.

• Manager Agent -- An AI that reads your codebase, proposes tasks, and manages the sprint
• Builder Agents -- AI agents that implement tasks in isolated git worktrees
• Templates -- Configurable prompt templates that control agent behavior (implementation, reviewer)

The CLI connects to the Dashboard via WebSocket for real-time communication. When the Dashboard is not open, it falls back to API polling.

Toban API

Hosted on Cloudflare Workers. Stores all data (tasks, sprints, agents, messages) and handles authentication via GitHub OAuth.

• Quality Scores -- Review results are aggregated into per-agent quality scores
• Failure DB -- Past failures and review rejections are stored to prevent recurring issues
• Knowledge -- Shared memory entries for cross-agent context preservation

How a Task Gets Done

1. You create a task (or the Manager proposes one)
2. Move the task to "In Progress" on the Sprint Board
3. The CLI picks it up and spawns a Builder agent in a git worktree
4. The Builder implements the change and commits
5. The CLI runs a reviewer template to perform structured code review
6. The CLI merges to main, pushes, and writes a review report
7. You review and approve (or reject) on the Sprint Board
8. Results feed back into Quality Scores and Failure DB

Communication

• Real-time: WebSocket between Dashboard and CLI (chat, agent activity, proposals)
• Persistent: REST API for task/sprint/agent data storage
• Git: Agents commit in worktrees, CLI pushes to GitHub

Security

• Agents run in isolated git worktrees (not your working directory)
• The Manager has read-only access to repositories
• Worker agents auto-start on tasks assigned to agent roles (manual approval mode planned)
• GitHub App tokens are refreshed automatically (1-hour expiry)

For more details, see the Setup Guide and Getting Started.