# geoffjay/tower architecture

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

- Interactive diagram: https://gitdiagram.com/geoffjay/tower
- Repository: https://github.com/geoffjay/tower

## Overview

Tower is a server-centered control and visibility system for coding-agent herds. Operators use the CLI/client to reach server APIs for agent sessions and task assignment; the server coordinates agent processes through a harness and persists operational state and events in SQLite. The repository also includes scheduling, messaging, inventory, streaming, MCP, and alternate user interfaces. The principal runtime wiring is only partly evidenced by the sampled sources, so uncertain route-registration and subsystem links are omitted.

Main entry points: [`crates/tower-server/src/storage.rs`](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/storage.rs) (SQLite and events), [`crates/tower-server/src/sessions.rs`](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/sessions.rs) (Agent sessions), [`crates/tower-driver/src/lib.rs`](https://github.com/geoffjay/tower/blob/main/crates/tower-driver/src/lib.rs) (Harness driver), [`crates/tower-server/src/tasks.rs`](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/tasks.rs) (Task queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Operator interfaces"]
  node_cli["Tower CLI<br/>[cli.rs]"]
  node_client["HTTP client<br/>[lib.rs]"]
  node_tui["Terminal UI<br/>[lib.rs]"]
  node_web["Web UI<br/>[lib.rs]"]
end

subgraph group_server["Server surfaces"]
  node_http["HTTP server<br/>[http.rs]"]
  node_auth["API auth<br/>[auth.rs]"]
  node_agents_api["Agent API<br/>[agents_api.rs]"]
  node_sse["Event stream<br/>[sse.rs]"]
  node_mcp["MCP interface<br/>[mcp.rs]"]
end

subgraph group_operations["Agent operations"]
  node_tasks["Task queue<br/>[tasks.rs]"]
  node_sessions["Agent sessions<br/>[sessions.rs]"]
  node_inventory["Agent inventory<br/>[inventory.rs]"]
  node_schedules["Schedules<br/>[schedules.rs]"]
  node_messaging["Agent messaging<br/>[messaging.rs]"]
  node_dialog["Agent dialog<br/>[dialog.rs]"]
  node_pump["Event pump<br/>[pump.rs]"]
end

subgraph group_domain["Domain and persistence"]
  node_core["Shared domain<br/>[lib.rs]"]
  node_storage[("SQLite and events<br/>[storage.rs]")]
end

subgraph group_integrations["Harness integration"]
  node_driver["Harness driver<br/>[lib.rs]"]
  node_herdr_driver["Herdr driver<br/>[herdr.rs]"]
end

node_operator(("Operator"))
node_herdr["Herdr panes"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"sends requests"| node_client
node_client -->|"HTTP requests"| node_http
node_http -->|"authenticates"| node_auth
node_tasks -->|"delivers prompts"| node_messaging
node_sessions -->|"reconciles agents"| node_inventory
node_sessions -->|"controls agents"| node_driver
node_driver -->|"implements harness"| node_herdr_driver
node_herdr_driver -.->|"runs CLI commands"| node_herdr
node_sessions -->|"writes session data"| node_storage
node_tasks -->|"writes task data"| node_storage
node_storage -->|"stores domain events"| node_core
node_pump -->|"consumes harness events"| node_driver
node_sse -->|"replays events"| node_storage

click node_cli "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/cli.rs"
click node_client "https://github.com/geoffjay/tower/blob/main/crates/tower-client/src/lib.rs"
click node_tui "https://github.com/geoffjay/tower/blob/main/crates/tower-tui/src/lib.rs"
click node_web "https://github.com/geoffjay/tower/blob/main/crates/tower-web/src/lib.rs"
click node_http "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/http.rs"
click node_auth "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/auth.rs"
click node_agents_api "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/agents_api.rs"
click node_tasks "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/tasks.rs"
click node_sessions "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/sessions.rs"
click node_inventory "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/inventory.rs"
click node_schedules "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/schedules.rs"
click node_messaging "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/messaging.rs"
click node_dialog "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/dialog.rs"
click node_pump "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/pump.rs"
click node_sse "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/sse.rs"
click node_mcp "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/mcp.rs"
click node_core "https://github.com/geoffjay/tower/blob/main/crates/tower-core/src/lib.rs"
click node_storage "https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/storage.rs"
click node_driver "https://github.com/geoffjay/tower/blob/main/crates/tower-driver/src/lib.rs"
click node_herdr_driver "https://github.com/geoffjay/tower/blob/main/crates/tower-driver/src/herdr.rs"

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_client,node_tui,node_web toneBlue
class node_http,node_auth,node_agents_api,node_sse,node_mcp toneAmber
class node_tasks,node_sessions,node_inventory,node_schedules,node_messaging,node_dialog,node_pump toneMint
class node_core,node_storage toneRose
class node_driver,node_herdr_driver,node_operator,node_herdr toneIndigo
```

## Components

### Operator interfaces

- [Tower CLI](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/cli.rs): `crates/tower-server/src/cli.rs`
- [HTTP client](https://github.com/geoffjay/tower/blob/main/crates/tower-client/src/lib.rs): `crates/tower-client/src/lib.rs`
- [Terminal UI](https://github.com/geoffjay/tower/blob/main/crates/tower-tui/src/lib.rs): `crates/tower-tui/src/lib.rs`
- [Web UI](https://github.com/geoffjay/tower/blob/main/crates/tower-web/src/lib.rs): `crates/tower-web/src/lib.rs`

### Server surfaces

- [HTTP server](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/http.rs): `crates/tower-server/src/http.rs`
- [API auth](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/auth.rs): `crates/tower-server/src/auth.rs`
- [Agent API](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/agents_api.rs): `crates/tower-server/src/agents_api.rs`
- [Event stream](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/sse.rs): `crates/tower-server/src/sse.rs`
- [MCP interface](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/mcp.rs): `crates/tower-server/src/mcp.rs`

### Agent operations

- [Task queue](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/tasks.rs): `crates/tower-server/src/tasks.rs`
- [Agent sessions](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/sessions.rs): `crates/tower-server/src/sessions.rs`
- [Agent inventory](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/inventory.rs): `crates/tower-server/src/inventory.rs`
- [Schedules](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/schedules.rs): `crates/tower-server/src/schedules.rs`
- [Agent messaging](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/messaging.rs): `crates/tower-server/src/messaging.rs`
- [Agent dialog](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/dialog.rs): `crates/tower-server/src/dialog.rs`
- [Event pump](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/pump.rs): `crates/tower-server/src/pump.rs`

### Domain and persistence

- [Shared domain](https://github.com/geoffjay/tower/blob/main/crates/tower-core/src/lib.rs): `crates/tower-core/src/lib.rs`
- [SQLite and events](https://github.com/geoffjay/tower/blob/main/crates/tower-server/src/storage.rs): `crates/tower-server/src/storage.rs`

### Harness integration

- [Harness driver](https://github.com/geoffjay/tower/blob/main/crates/tower-driver/src/lib.rs): `crates/tower-driver/src/lib.rs`
- [Herdr driver](https://github.com/geoffjay/tower/blob/main/crates/tower-driver/src/herdr.rs): `crates/tower-driver/src/herdr.rs`

### Other components

- **Operator**
- **Herdr panes**

## Connections

- Operator → Tower CLI: runs commands
- Tower CLI → HTTP client: sends requests
- HTTP client → HTTP server: HTTP requests
- HTTP server → API auth: authenticates
- Task queue → Agent messaging: delivers prompts
- Agent sessions → Agent inventory: reconciles agents
- Agent sessions → Harness driver: controls agents
- Harness driver → Herdr driver: implements harness
- Herdr driver → Herdr panes: runs CLI commands
- Agent sessions → SQLite and events: writes session data
- Task queue → SQLite and events: writes task data
- SQLite and events → Shared domain: stores domain events
- Event pump → Harness driver: consumes harness events
- Event stream → SQLite and events: replays events