# do-whilefor/x-loom architecture

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

- Interactive diagram: https://gitdiagram.com/do-whilefor/x-loom
- Repository: https://github.com/do-whilefor/x-loom

## Overview

X-Loom is a Linux collaborative exploration system: users manage projects and review shared exploration state in a Web workbench, while a Dispatcher schedules Docker/Kali Workers to investigate and contribute observations, decisions, and completion evidence. The Server exposes the board API and persists project state; workers use an agent loop and tools, with graph actions bridged back through the Dispatcher. The README documents these operating roles; some subsystem links are based on documented capabilities and directory structure because their source was not sampled.

Main entry points: [`internal/server/server.go`](https://github.com/do-whilefor/x-loom/blob/main/internal/server/server.go) (HTTP API), [`internal/docker/client.go`](https://github.com/do-whilefor/x-loom/blob/main/internal/docker/client.go) (Docker runtime), [`internal/worker/worker.go`](https://github.com/do-whilefor/x-loom/blob/main/internal/worker/worker.go) (Worker runtime), [`cmd/xloom/main.go`](https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/main.go) (Command CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product entrypoints"]
  node_cli["Command CLI<br/>[main.go]"]
  node_servecmd["Serve command<br/>[serve.go]"]
  node_dispatchcmd["Dispatch command<br/>[dispatch.go]"]
  node_workercmd["Worker command<br/>[worker.go]"]
end

subgraph group_board["Project board"]
  node_server["HTTP API<br/>[server.go]"]
  node_boardstate["Board state<br/>[state.go]"]
  node_boardstore[("SQLite store<br/>[store.go]")]
  node_contract["Evidence policy<br/>[contract.go]"]
end

subgraph group_dispatch["Task orchestration"]
  node_dispatcher["Scheduler<br/>[scheduler.go]"]
  node_dispatchclient["Board client<br/>[client.go]"]
  node_docker["Docker runtime<br/>[client.go]"]
end

subgraph group_worker["Worker execution"]
  node_worker["Worker runtime<br/>[worker.go]"]
  node_agent["Agent loop<br/>[loop.go]"]
  node_provider["Anthropic provider<br/>[anthropic.go]"]
  node_tools["Worker tools<br/>[tools.go]"]
  node_graphbridge["Graph protocol<br/>[graph_protocol.go]"]
end

subgraph group_web["Web workbench"]
  node_webapp["Workbench UI<br/>[app.js]"]
  node_webapi["Browser API client<br/>[api.js]"]
  node_graphview["Graph visualization<br/>[graph-view.js]"]
  node_webembed["Embedded assets<br/>[embed.go]"]
end

node_user(("Project user"))
node_modelservice(("Model service"))
node_dockerengine(("Docker Engine"))
node_browser(("Browser user"))

node_cli -->|"runs serve"| node_servecmd
node_cli -->|"runs dispatch"| node_dispatchcmd
node_cli -->|"runs worker"| node_workercmd
node_user -->|"manages projects"| node_webapp
node_webapp -->|"requests API"| node_webapi
node_webapp -->|"renders graph"| node_graphview
node_webapi -->|"HTTP requests"| node_server
node_servecmd -->|"serves API"| node_server
node_server -->|"reads and updates"| node_boardstate
node_server -->|"persists state"| node_boardstore
node_server -->|"serves assets"| node_webembed
node_server -->|"checks evidence"| node_contract
node_dispatcher -->|"queries board"| node_dispatchclient
node_dispatcher -->|"runs workers"| node_docker
node_dispatchclient -->|"calls board API"| node_server
node_docker -->|"controls containers"| node_dockerengine
node_docker -->|"executes worker"| node_worker
node_workercmd -->|"starts execution"| node_worker
node_worker -->|"runs agent loop"| node_agent
node_agent -->|"sends model requests"| node_provider
node_provider -->|"requests completions"| node_modelservice
node_agent -->|"dispatches tools"| node_tools
node_worker -->|"handles graph actions"| node_graphbridge
node_docker -->|"bridges graph events"| node_graphbridge
node_graphbridge -->|"submits graph actions"| node_server

click node_cli "https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/main.go"
click node_servecmd "https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/serve.go"
click node_dispatchcmd "https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/dispatch.go"
click node_workercmd "https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/worker.go"
click node_server "https://github.com/do-whilefor/x-loom/blob/main/internal/server/server.go"
click node_boardstate "https://github.com/do-whilefor/x-loom/blob/main/internal/board/state.go"
click node_boardstore "https://github.com/do-whilefor/x-loom/blob/main/internal/board/store.go"
click node_contract "https://github.com/do-whilefor/x-loom/blob/main/internal/contract/contract.go"
click node_dispatcher "https://github.com/do-whilefor/x-loom/blob/main/internal/dispatcher/scheduler.go"
click node_dispatchclient "https://github.com/do-whilefor/x-loom/blob/main/internal/dispatcher/client.go"
click node_docker "https://github.com/do-whilefor/x-loom/blob/main/internal/docker/client.go"
click node_worker "https://github.com/do-whilefor/x-loom/blob/main/internal/worker/worker.go"
click node_agent "https://github.com/do-whilefor/x-loom/blob/main/internal/agent/loop.go"
click node_provider "https://github.com/do-whilefor/x-loom/blob/main/internal/provider/anthropic.go"
click node_tools "https://github.com/do-whilefor/x-loom/blob/main/internal/tools/tools.go"
click node_graphbridge "https://github.com/do-whilefor/x-loom/blob/main/internal/worker/graph_protocol.go"
click node_webapp "https://github.com/do-whilefor/x-loom/blob/main/web/static/app.js"
click node_webapi "https://github.com/do-whilefor/x-loom/blob/main/web/static/api.js"
click node_graphview "https://github.com/do-whilefor/x-loom/blob/main/web/static/graph-view.js"
click node_webembed "https://github.com/do-whilefor/x-loom/blob/main/web/embed.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_servecmd,node_dispatchcmd,node_workercmd,node_user,node_browser toneBlue
class node_server,node_boardstate,node_boardstore,node_contract toneAmber
class node_dispatcher,node_dispatchclient,node_docker toneMint
class node_worker,node_agent,node_provider,node_tools,node_graphbridge toneRose
class node_webapp,node_webapi,node_graphview,node_webembed,node_modelservice,node_dockerengine toneIndigo
```

## Components

### Product entrypoints

- [Command CLI](https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/main.go): `cmd/xloom/main.go`
- [Serve command](https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/serve.go): `cmd/xloom/serve.go`
- [Dispatch command](https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/dispatch.go): `cmd/xloom/dispatch.go`
- [Worker command](https://github.com/do-whilefor/x-loom/blob/main/cmd/xloom/worker.go): `cmd/xloom/worker.go`

### Project board

- [HTTP API](https://github.com/do-whilefor/x-loom/blob/main/internal/server/server.go): `internal/server/server.go`
- [Board state](https://github.com/do-whilefor/x-loom/blob/main/internal/board/state.go): `internal/board/state.go`
- [SQLite store](https://github.com/do-whilefor/x-loom/blob/main/internal/board/store.go): `internal/board/store.go`
- [Evidence policy](https://github.com/do-whilefor/x-loom/blob/main/internal/contract/contract.go): `internal/contract/contract.go`

### Task orchestration

- [Scheduler](https://github.com/do-whilefor/x-loom/blob/main/internal/dispatcher/scheduler.go): `internal/dispatcher/scheduler.go`
- [Board client](https://github.com/do-whilefor/x-loom/blob/main/internal/dispatcher/client.go): `internal/dispatcher/client.go`
- [Docker runtime](https://github.com/do-whilefor/x-loom/blob/main/internal/docker/client.go): `internal/docker/client.go`

### Worker execution

- [Worker runtime](https://github.com/do-whilefor/x-loom/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [Agent loop](https://github.com/do-whilefor/x-loom/blob/main/internal/agent/loop.go): `internal/agent/loop.go`
- [Anthropic provider](https://github.com/do-whilefor/x-loom/blob/main/internal/provider/anthropic.go): `internal/provider/anthropic.go`
- [Worker tools](https://github.com/do-whilefor/x-loom/blob/main/internal/tools/tools.go): `internal/tools/tools.go`
- [Graph protocol](https://github.com/do-whilefor/x-loom/blob/main/internal/worker/graph_protocol.go): `internal/worker/graph_protocol.go`

### Web workbench

- [Workbench UI](https://github.com/do-whilefor/x-loom/blob/main/web/static/app.js): `web/static/app.js`
- [Browser API client](https://github.com/do-whilefor/x-loom/blob/main/web/static/api.js): `web/static/api.js`
- [Graph visualization](https://github.com/do-whilefor/x-loom/blob/main/web/static/graph-view.js): `web/static/graph-view.js`
- [Embedded assets](https://github.com/do-whilefor/x-loom/blob/main/web/embed.go): `web/embed.go`

### Other components

- **Project user**
- **Model service**
- **Docker Engine**
- **Browser user**

## Connections

- Command CLI → Serve command: runs serve
- Command CLI → Dispatch command: runs dispatch
- Command CLI → Worker command: runs worker
- Project user → Workbench UI: manages projects
- Workbench UI → Browser API client: requests API
- Workbench UI → Graph visualization: renders graph
- Browser API client → HTTP API: HTTP requests
- Serve command → HTTP API: serves API
- HTTP API → Board state: reads and updates
- HTTP API → SQLite store: persists state
- HTTP API → Embedded assets: serves assets
- HTTP API → Evidence policy: checks evidence
- Scheduler → Board client: queries board
- Scheduler → Docker runtime: runs workers
- Board client → HTTP API: calls board API
- Docker runtime → Docker Engine: controls containers
- Docker runtime → Worker runtime: executes worker
- Worker command → Worker runtime: starts execution
- Worker runtime → Agent loop: runs agent loop
- Agent loop → Anthropic provider: sends model requests
- Anthropic provider → Model service: requests completions
- Agent loop → Worker tools: dispatches tools
- Worker runtime → Graph protocol: handles graph actions
- Docker runtime → Graph protocol: bridges graph events
- Graph protocol → HTTP API: submits graph actions