# clickety-clacks/tightbeam architecture

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

- Interactive diagram: https://gitdiagram.com/clickety-clacks/tightbeam
- Repository: https://github.com/clickety-clacks/tightbeam

## Overview

Tightbeam is a standalone service that runs an organization of vendor-harness AI agents. The main workflow is an owner filing work, the organization executing and reviewing it, and owner-only decisions being returned for action; CLI commands also let operators and external agents interact with the gateway. The README documents durable records, deterministic rules, cross-vendor review, and recovery, but most Elixir runtime modules were not sampled. Those subsystems are represented at their exact tree paths; connections not established by the README or excerpts are omitted.

Main entry points: [`cli/src/main.rs`](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/main.rs) (CLI entry), [`lib/tightbeam/work_items.ex`](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/work_items.ex) (Ticket work), [`cli/src/ceremonies.rs`](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/ceremonies.rs) (Setup ceremonies), [`cli/src/dispatch.rs`](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/dispatch.rs) (Gateway dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway and access"]
  node_gateway_service["Gateway service<br/>[gateway.ex]"]
  node_wire_router["Wire router<br/>[router.ex]"]
  node_acp_adapter["ACP adapters<br/>[adapter.ex]"]
end

subgraph group_work["Organizational work"]
  node_ticket_work["Ticket work<br/>[work_items.ex]"]
  node_assignment["Assignments<br/>[assignments.ex]"]
  node_review["Cross-vendor review<br/>[roles.ex]"]
  node_owner_decisions["Owner decisions<br/>[escalation.ex]"]
end

subgraph group_execution["Agent execution"]
  node_harnesses["Vendor harnesses<br/>[claude.ex]"]
  node_turn_lifecycle["Turn lifecycle<br/>[turn_lifecycle.ex]"]
end

subgraph group_record["Rules and record"]
  node_durable_record[("Durable record<br/>[db.ex]")]
  node_event_log[("Attributed history<br/>[event_log.ex]")]
  node_deterministic_rules["Deterministic rules<br/>[rules.ex]"]
end

subgraph group_cli["CLI operations"]
  node_cli_entry["CLI entry<br/>[main.rs]"]
  node_cli_args["Command parsing<br/>[args.rs]"]
  node_cli_dispatch["Gateway dispatch<br/>[dispatch.rs]"]
  node_cli_setup["Setup ceremonies<br/>[ceremonies.rs]"]
  node_cli_harnesses["Harness catalog<br/>[harnesses.rs]"]
  node_cli_preflight["Host preflight<br/>[preflight.rs]"]
  node_cli_probe["Environment probe<br/>[probe.rs]"]
  node_cli_containment["Process containment<br/>[contain.rs]"]
  node_cli_process["Child processes<br/>[child_process.rs]"]
  node_cli_oauth["Anthropic OAuth<br/>[anthropic_oauth.rs]"]
  node_cli_catalog["Catalog probe<br/>[catalog_probe.rs]"]
  node_cli_visitor["Visitor identity<br/>[visitor.rs]"]
  node_cli_lease["Request leases<br/>[lease.rs]"]
  node_cli_base_dir["Base directory<br/>[base_dir.rs]"]
  node_cli_onboard["Onboarding output<br/>[onboard_emit.rs]"]
  node_cli_harness_process["Harness process<br/>[harness_process.rs]"]
end

node_owner(("Owner"))
node_external_agent(("External agent"))

node_owner -->|"files tickets"| node_ticket_work
node_ticket_work -.->|"organizes work"| node_assignment
node_assignment -.->|"assigns agents"| node_harnesses
node_harnesses -.->|"runs turns"| node_turn_lifecycle
node_turn_lifecycle -->|"supports review"| node_review
node_review -->|"triages decisions"| node_owner_decisions
node_owner_decisions -->|"requests decision"| node_owner
node_ticket_work -->|"records work"| node_durable_record
node_durable_record -->|"preserves history"| node_event_log
node_deterministic_rules -->|"governs work"| node_ticket_work
node_external_agent -->|"invokes CLI"| node_cli_entry
node_cli_entry -->|"routes rail-exec"| node_cli_containment
node_cli_entry -->|"routes harness-exec"| node_cli_harness_process
node_cli_entry -->|"routes catalog-probe"| node_cli_catalog
node_cli_dispatch -->|"calls gateway"| node_gateway_service
node_cli_harnesses -->|"loads catalog via"| node_cli_dispatch
node_cli_preflight -->|"uses catalog"| node_cli_harnesses
node_cli_setup -->|"uses OAuth"| node_cli_oauth
node_cli_setup -->|"bounds calls"| node_cli_lease
node_cli_entry -.->|"parses commands"| node_cli_args
node_cli_entry -.->|"dispatches commands"| node_cli_dispatch
node_cli_probe -.->|"inspects harnesses"| node_cli_harnesses
node_cli_entry -.->|"resolves location"| node_cli_base_dir
node_cli_setup -.->|"emits onboarding"| node_cli_onboard
node_cli_entry -.->|"handles identity"| node_cli_visitor

click node_gateway_service "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/gateway.ex"
click node_wire_router "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/wire/router.ex"
click node_acp_adapter "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/acp/adapter.ex"
click node_ticket_work "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/work_items.ex"
click node_assignment "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/assignments.ex"
click node_review "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/roles.ex"
click node_owner_decisions "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/escalation.ex"
click node_harnesses "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/harness/claude.ex"
click node_turn_lifecycle "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/turn_lifecycle.ex"
click node_durable_record "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/db.ex"
click node_event_log "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/event_log.ex"
click node_deterministic_rules "https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/rules.ex"
click node_cli_entry "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/main.rs"
click node_cli_args "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/args.rs"
click node_cli_dispatch "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/dispatch.rs"
click node_cli_setup "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/ceremonies.rs"
click node_cli_harnesses "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/harnesses.rs"
click node_cli_preflight "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/preflight.rs"
click node_cli_probe "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/probe.rs"
click node_cli_containment "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/contain.rs"
click node_cli_process "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/child_process.rs"
click node_cli_oauth "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/anthropic_oauth.rs"
click node_cli_catalog "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/catalog_probe.rs"
click node_cli_visitor "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/visitor.rs"
click node_cli_lease "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/lease.rs"
click node_cli_base_dir "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/base_dir.rs"
click node_cli_onboard "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/onboard_emit.rs"
click node_cli_harness_process "https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/harness_process.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_gateway_service,node_wire_router,node_acp_adapter toneBlue
class node_ticket_work,node_assignment,node_review,node_owner_decisions toneAmber
class node_harnesses,node_turn_lifecycle toneMint
class node_durable_record,node_event_log,node_deterministic_rules toneRose
class node_cli_entry,node_cli_args,node_cli_dispatch,node_cli_setup,node_cli_harnesses,node_cli_preflight,node_cli_probe,node_cli_containment,node_cli_process,node_cli_oauth,node_cli_catalog,node_cli_visitor,node_cli_lease,node_cli_base_dir,node_cli_onboard,node_cli_harness_process,node_owner,node_external_agent toneIndigo
```

## Components

### Gateway and access

- [Gateway service](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/gateway.ex): `lib/tightbeam/gateway.ex`
- [Wire router](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/wire/router.ex): `lib/tightbeam/wire/router.ex`
- [ACP adapters](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/acp/adapter.ex): `lib/tightbeam/acp/adapter.ex`

### Organizational work

- [Ticket work](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/work_items.ex): `lib/tightbeam/work_items.ex`
- [Assignments](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/assignments.ex): `lib/tightbeam/assignments.ex`
- [Cross-vendor review](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/roles.ex): `lib/tightbeam/roles.ex`
- [Owner decisions](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/escalation.ex): `lib/tightbeam/escalation.ex`

### Agent execution

- [Vendor harnesses](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/harness/claude.ex): `lib/tightbeam/harness/claude.ex`
- [Turn lifecycle](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/turn_lifecycle.ex): `lib/tightbeam/turn_lifecycle.ex`

### Rules and record

- [Durable record](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/db.ex): `lib/tightbeam/db.ex`
- [Attributed history](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/event_log.ex): `lib/tightbeam/event_log.ex`
- [Deterministic rules](https://github.com/clickety-clacks/tightbeam/blob/main/lib/tightbeam/rules.ex): `lib/tightbeam/rules.ex`

### CLI operations

- [CLI entry](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/main.rs): `cli/src/main.rs`
- [Command parsing](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/args.rs): `cli/src/args.rs`
- [Gateway dispatch](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/dispatch.rs): `cli/src/dispatch.rs`
- [Setup ceremonies](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/ceremonies.rs): `cli/src/ceremonies.rs`
- [Harness catalog](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/harnesses.rs): `cli/src/harnesses.rs`
- [Host preflight](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/preflight.rs): `cli/src/preflight.rs`
- [Environment probe](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/probe.rs): `cli/src/probe.rs`
- [Process containment](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/contain.rs): `cli/src/contain.rs`
- [Child processes](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/child_process.rs): `cli/src/child_process.rs`
- [Anthropic OAuth](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/anthropic_oauth.rs): `cli/src/anthropic_oauth.rs`
- [Catalog probe](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/catalog_probe.rs): `cli/src/catalog_probe.rs`
- [Visitor identity](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/visitor.rs): `cli/src/visitor.rs`
- [Request leases](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/lease.rs): `cli/src/lease.rs`
- [Base directory](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/base_dir.rs): `cli/src/base_dir.rs`
- [Onboarding output](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/onboard_emit.rs): `cli/src/onboard_emit.rs`
- [Harness process](https://github.com/clickety-clacks/tightbeam/blob/main/cli/src/harness_process.rs): `cli/src/harness_process.rs`

### Other components

- **Owner**
- **External agent**

## Connections

- Owner → Ticket work: files tickets
- Ticket work → Assignments: organizes work
- Assignments → Vendor harnesses: assigns agents
- Vendor harnesses → Turn lifecycle: runs turns
- Turn lifecycle → Cross-vendor review: supports review
- Cross-vendor review → Owner decisions: triages decisions
- Owner decisions → Owner: requests decision
- Ticket work → Durable record: records work
- Durable record → Attributed history: preserves history
- Deterministic rules → Ticket work: governs work
- External agent → CLI entry: invokes CLI
- CLI entry → Process containment: routes rail-exec (evidence: `cli/src/main.rs`)
- CLI entry → Harness process: routes harness-exec (evidence: `cli/src/main.rs`)
- CLI entry → Catalog probe: routes catalog-probe (evidence: `cli/src/main.rs`)
- Gateway dispatch → Gateway service: calls gateway (evidence: `cli/src/dispatch.rs`)
- Harness catalog → Gateway dispatch: loads catalog via (evidence: `cli/src/harnesses.rs`)
- Host preflight → Harness catalog: uses catalog (evidence: `cli/src/preflight.rs`)
- Setup ceremonies → Anthropic OAuth: uses OAuth (evidence: `cli/src/ceremonies.rs`)
- Setup ceremonies → Request leases: bounds calls (evidence: `cli/src/ceremonies.rs`)
- CLI entry → Command parsing: parses commands (evidence: `cli/src/main.rs`)
- CLI entry → Gateway dispatch: dispatches commands (evidence: `cli/src/main.rs`)
- Environment probe → Harness catalog: inspects harnesses (evidence: `cli/src/probe.rs`)
- CLI entry → Base directory: resolves location (evidence: `cli/src/main.rs`)
- Setup ceremonies → Onboarding output: emits onboarding (evidence: `cli/src/ceremonies.rs`)
- CLI entry → Visitor identity: handles identity (evidence: `cli/src/main.rs`)
