# kaas-team/factory architecture

> Architecture diagram of the GitHub repository kaas-team/factory, 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/kaas-team/factory
- Repository: https://github.com/kaas-team/factory

## Overview

KaaS Factory is a goal-to-reviewed-PR automation product. Its main workflow turns goals into ticket graphs, reconciles tickets into parallel agent sessions, observes and verifies their changes, then submits passing work to a merge queue. The CLI is the principal entry point; the core coordinates the loop through ports, while tracker, dispatcher, observer, and queue implementations provide the work and integrations. The README documents additional planning, setup, steering, evaluation, and client capabilities. Some implementation paths are unsampled, so those branches are shown only where documented or evidenced by the source index.

Main entry points: [`internal/core/core.go`](https://github.com/kaas-team/factory/blob/main/internal/core/core.go) (Control Core), [`cmd/factory/main.go`](https://github.com/kaas-team/factory/blob/main/cmd/factory/main.go) (Factory CLI), [`internal/reconcile/run.go`](https://github.com/kaas-team/factory/blob/main/internal/reconcile/run.go) (Reconcile Loop), [`internal/mergeq/run.go`](https://github.com/kaas-team/factory/blob/main/internal/mergeq/run.go) (Merge Queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Clients"]
  node_cli["Factory CLI<br/>[main.go]"]
  node_mcp["MCP Server<br/>[mcp.go]"]
  node_tui["Terminal Board<br/>[tui.go]"]
  node_dashboard["Web Dashboard<br/>[dashboard.go]"]
  node_serve["Service Host<br/>[serve.go]"]
end

subgraph group_workflow["Work Orchestration"]
  node_control["Control Core<br/>[core.go]"]
  node_planner["Goal Planner<br/>[plancmd.go]"]
  node_ticketgraph["Ticket Graph<br/>[graph.go]"]
  node_reconciler["Reconcile Loop<br/>[run.go]"]
end

subgraph group_execution["Execution and Verification"]
  node_tracker["Issue Tracker<br/>[tracker.go]"]
  node_dispatcher["Agent Dispatcher<br/>[local.go]"]
  node_observer["Run Observer<br/>[observe.go]"]
  node_gates["Quality Gates<br/>[gate.go]"]
  node_mergequeue["Merge Queue<br/>[run.go]"]
end

subgraph group_state["State and Insights"]
  node_store[("Persistent Store<br/>[store.go]")]
  node_meter["Usage Meter<br/>[meter.go]"]
end

subgraph group_capabilities["Product Capabilities"]
  node_first_run["Repository Audit<br/>[firstrun.go]"]
  node_packs["Workflow Packs<br/>[command.go]"]
  node_evaluation["Agent Evaluation<br/>[eval.go]"]
  node_design["Workflow Design<br/>[design.go]"]
  node_smoke["Integration Smoke<br/>[run.go]"]
end

node_user(("Operator"))
node_github{{"GitHub"}}
node_repo["Target Repository"]

node_user -->|"runs commands"| node_cli
node_cli -->|"invokes planning"| node_planner
node_planner -->|"builds plan"| node_ticketgraph
node_cli -->|"mounts run commands"| node_control
node_control -->|"runs decisions"| node_reconciler
node_control -->|"queues finished work"| node_mergequeue
node_reconciler -->|"dispatches sessions"| node_dispatcher
node_reconciler -->|"updates ticket state"| node_tracker
node_control -->|"uses workflows"| node_ticketgraph
node_control -->|"reconciles observations"| node_observer
node_control -->|"tracks usage"| node_meter
node_mergequeue -.->|"coordinates landing"| node_tracker
node_dispatcher -.->|"changes code"| node_repo
node_gates -.->|"checks changes"| node_repo
node_control -.->|"persists state"| node_store
node_user -->|"connects tools"| node_mcp
node_mcp -->|"acts through control"| node_control
node_user -->|"steers tickets"| node_tui
node_tui -->|"uses control API"| node_control
node_user -->|"starts service"| node_serve
node_serve -->|"hosts dashboard"| node_dashboard
node_user -->|"audits repository"| node_first_run
node_first_run -->|"inspects files"| node_repo
node_user -->|"manages packs"| node_packs
node_user -->|"runs evaluations"| node_evaluation
node_user -->|"designs workflows"| node_design
node_user -->|"runs smoke check"| node_smoke
node_tracker -.->|"reads and updates"| node_github
node_mergequeue -->|"lands pull requests"| node_github
node_control -->|"verifies results"| node_gates

click node_cli "https://github.com/kaas-team/factory/blob/main/cmd/factory/main.go"
click node_mcp "https://github.com/kaas-team/factory/blob/main/internal/mcp/mcp.go"
click node_tui "https://github.com/kaas-team/factory/blob/main/internal/tui/tui.go"
click node_control "https://github.com/kaas-team/factory/blob/main/internal/core/core.go"
click node_planner "https://github.com/kaas-team/factory/blob/main/internal/plancmd/plancmd.go"
click node_ticketgraph "https://github.com/kaas-team/factory/blob/main/internal/graph/graph.go"
click node_reconciler "https://github.com/kaas-team/factory/blob/main/internal/reconcile/run.go"
click node_tracker "https://github.com/kaas-team/factory/blob/main/internal/tracker/github/tracker.go"
click node_dispatcher "https://github.com/kaas-team/factory/blob/main/internal/dispatch/local/local.go"
click node_observer "https://github.com/kaas-team/factory/blob/main/internal/observe/observe.go"
click node_gates "https://github.com/kaas-team/factory/blob/main/internal/gate/gate.go"
click node_mergequeue "https://github.com/kaas-team/factory/blob/main/internal/mergeq/run.go"
click node_store "https://github.com/kaas-team/factory/blob/main/internal/store/store.go"
click node_meter "https://github.com/kaas-team/factory/blob/main/internal/meter/meter.go"
click node_dashboard "https://github.com/kaas-team/factory/blob/main/internal/dashboard/dashboard.go"
click node_serve "https://github.com/kaas-team/factory/blob/main/internal/serve/serve.go"
click node_first_run "https://github.com/kaas-team/factory/blob/main/internal/firstrun/firstrun.go"
click node_packs "https://github.com/kaas-team/factory/blob/main/internal/packs/command.go"
click node_evaluation "https://github.com/kaas-team/factory/blob/main/internal/eval/eval.go"
click node_design "https://github.com/kaas-team/factory/blob/main/internal/design/design.go"
click node_smoke "https://github.com/kaas-team/factory/blob/main/internal/smoke/run.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_mcp,node_tui,node_dashboard,node_serve toneBlue
class node_control,node_planner,node_ticketgraph,node_reconciler toneAmber
class node_tracker,node_dispatcher,node_observer,node_gates,node_mergequeue toneMint
class node_store,node_meter toneRose
class node_first_run,node_packs,node_evaluation,node_design,node_smoke,node_user,node_github,node_repo toneIndigo
```

## Components

### Entry and Clients

- [Factory CLI](https://github.com/kaas-team/factory/blob/main/cmd/factory/main.go): `cmd/factory/main.go`
- [MCP Server](https://github.com/kaas-team/factory/blob/main/internal/mcp/mcp.go): `internal/mcp/mcp.go`
- [Terminal Board](https://github.com/kaas-team/factory/blob/main/internal/tui/tui.go): `internal/tui/tui.go`
- [Web Dashboard](https://github.com/kaas-team/factory/blob/main/internal/dashboard/dashboard.go): `internal/dashboard/dashboard.go`
- [Service Host](https://github.com/kaas-team/factory/blob/main/internal/serve/serve.go): `internal/serve/serve.go`

### Work Orchestration

- [Control Core](https://github.com/kaas-team/factory/blob/main/internal/core/core.go): `internal/core/core.go`
- [Goal Planner](https://github.com/kaas-team/factory/blob/main/internal/plancmd/plancmd.go): `internal/plancmd/plancmd.go`
- [Ticket Graph](https://github.com/kaas-team/factory/blob/main/internal/graph/graph.go): `internal/graph/graph.go`
- [Reconcile Loop](https://github.com/kaas-team/factory/blob/main/internal/reconcile/run.go): `internal/reconcile/run.go`

### Execution and Verification

- [Issue Tracker](https://github.com/kaas-team/factory/blob/main/internal/tracker/github/tracker.go): `internal/tracker/github/tracker.go`
- [Agent Dispatcher](https://github.com/kaas-team/factory/blob/main/internal/dispatch/local/local.go): `internal/dispatch/local/local.go`
- [Run Observer](https://github.com/kaas-team/factory/blob/main/internal/observe/observe.go): `internal/observe/observe.go`
- [Quality Gates](https://github.com/kaas-team/factory/blob/main/internal/gate/gate.go): `internal/gate/gate.go`
- [Merge Queue](https://github.com/kaas-team/factory/blob/main/internal/mergeq/run.go): `internal/mergeq/run.go`

### State and Insights

- [Persistent Store](https://github.com/kaas-team/factory/blob/main/internal/store/store.go): `internal/store/store.go`
- [Usage Meter](https://github.com/kaas-team/factory/blob/main/internal/meter/meter.go): `internal/meter/meter.go`

### Product Capabilities

- [Repository Audit](https://github.com/kaas-team/factory/blob/main/internal/firstrun/firstrun.go): `internal/firstrun/firstrun.go`
- [Workflow Packs](https://github.com/kaas-team/factory/blob/main/internal/packs/command.go): `internal/packs/command.go`
- [Agent Evaluation](https://github.com/kaas-team/factory/blob/main/internal/eval/eval.go): `internal/eval/eval.go`
- [Workflow Design](https://github.com/kaas-team/factory/blob/main/internal/design/design.go): `internal/design/design.go`
- [Integration Smoke](https://github.com/kaas-team/factory/blob/main/internal/smoke/run.go): `internal/smoke/run.go`

### Other components

- **Operator**
- **GitHub**
- **Target Repository**

## Connections

- Operator → Factory CLI: runs commands (evidence: `cmd/factory/main.go`)
- Factory CLI → Goal Planner: invokes planning (evidence: `cmd/factory/main.go`)
- Goal Planner → Ticket Graph: builds plan (evidence: `internal/plancmd/plancmd.go`)
- Factory CLI → Control Core: mounts run commands (evidence: `cmd/factory/main.go`)
- Control Core → Reconcile Loop: runs decisions (evidence: `internal/core/core.go`)
- Control Core → Merge Queue: queues finished work (evidence: `internal/core/core.go`)
- Reconcile Loop → Agent Dispatcher: dispatches sessions (evidence: `internal/reconcile/run.go`)
- Reconcile Loop → Issue Tracker: updates ticket state (evidence: `internal/reconcile/run.go`)
- Control Core → Ticket Graph: uses workflows (evidence: `internal/core/core.go`)
- Control Core → Run Observer: reconciles observations (evidence: `internal/core/core.go`)
- Control Core → Usage Meter: tracks usage (evidence: `internal/core/core.go`)
- Merge Queue → Issue Tracker: coordinates landing
- Agent Dispatcher → Target Repository: changes code
- Quality Gates → Target Repository: checks changes
- Control Core → Persistent Store: persists state
- Operator → MCP Server: connects tools (evidence: `README.md`)
- MCP Server → Control Core: acts through control (evidence: `internal/mcp/mcp.go`)
- Operator → Terminal Board: steers tickets (evidence: `internal/tui/tui.go`)
- Terminal Board → Control Core: uses control API (evidence: `internal/tui/tui.go`)
- Operator → Service Host: starts service (evidence: `README.md`)
- Service Host → Web Dashboard: hosts dashboard (evidence: `internal/dashboard/dashboard.go`)
- Operator → Repository Audit: audits repository (evidence: `README.md`)
- Repository Audit → Target Repository: inspects files (evidence: `README.md`)
- Operator → Workflow Packs: manages packs (evidence: `README.md`)
- Operator → Agent Evaluation: runs evaluations (evidence: `README.md`)
- Operator → Workflow Design: designs workflows (evidence: `README.md`)
- Operator → Integration Smoke: runs smoke check (evidence: `README.md`)
- Issue Tracker → GitHub: reads and updates
- Merge Queue → GitHub: lands pull requests (evidence: `README.md`)
- Control Core → Quality Gates: verifies results (evidence: `README.md`)
