huskies/.huskies/specs/tech/STACK.md

# Tech Stack

## Backend
- **Language:** Rust
- **Framework:** Poem (HTTP + WebSocket + OpenAPI)
- **Database:** SQLite via sqlx + rusqlite
- **State:** BFT CRDT replicated document backed by SQLite
- **Agents:** Claude Code CLI spawned in PTY pseudo-terminals
- **Package manager:** cargo

## Frontend
- **Language:** TypeScript + React
- **Build:** Vite
- **Package manager:** npm
- **Testing:** Vitest (unit), Playwright (e2e)

## Deployment
- Single Rust binary with embedded React frontend (rust-embed)
- Three modes: standard server, headless build agent (`--rendezvous`), multi-project gateway (`--gateway`)
- Docker container with OrbStack recommended on macOS

## Project Layout
```
server/src/          — Rust backend
frontend/src/        — React frontend
crates/bft-json-crdt/ — CRDT library
.huskies/            — Pipeline config, agent config, specs
script/              — test, build, lint scripts
docker/              — Dockerfile and docker-compose
website/             — Static marketing/docs site
```

## Source Map

One row per directory or top-level file. Descriptions are pulled from the module's `//!` doc-comment where present. **Use this to know where to look — do not re-discover the codebase via grep.**

### Top-level backend files (`server/src/`)

| File | Purpose |
|------|---------|
| `server/src/agent_log.rs` | Agent log persistence — reads and writes JSONL agent event logs to disk. |
| `server/src/agent_mode.rs` | Headless build-agent mode for distributed, rendezvous-based story processing. |
| `server/src/cli.rs` | Command-line argument parsing for the huskies binary. |
| `server/src/crdt_wire.rs` | CRDT wire codec — serialization format for `SignedOp` sync messages between nodes. |
| `server/src/gateway.rs` | Multi-project gateway — entrypoint wiring and route tree.  When `huskies --gateway` is used, the server starts in gateway mode. B… |
| `server/src/gateway_relay.rs` | Gateway relay task — pushes project status events to the gateway via WebSocket.  When `gateway_url` is configured in `project.tom… |
| `server/src/log_buffer.rs` | Bounded in-memory ring buffer for server log output.  Use the [`slog!`] macro (INFO), [`slog_warn!`] (WARN), or [`slog_error!`] (… |
| `server/src/main.rs` | Huskies server — entry point, CLI argument parsing, and server startup. |
| `server/src/mesh.rs` | Peer mesh discovery — supplementary CRDT sync connections between build agents.  When mesh discovery is enabled, a build agent pe… |
| `server/src/node_identity.rs` | Node identity — Ed25519 keypair foundation for distributed huskies.  Each huskies node has a stable identity derived from an Ed25… |
| `server/src/rebuild.rs` | Server rebuild and restart logic shared between the MCP tool and Matrix bot command. |
| `server/src/services.rs` | Shared services bundle — common state threaded through HTTP handlers and chat transports.  `Services` bundles the fields that eve… |
| `server/src/state.rs` | Session state — global mutable state shared across the server (project root, cancellation). |
| `server/src/store.rs` | Key-value store — JSON-backed persistent storage for user settings and preferences. |
| `server/src/workflow.rs` | Workflow module: test result tracking and acceptance evaluation. |

### Backend modules (`server/src/`)

| Path | Purpose |
|------|---------|
| `server/src/` |  |
| `server/src/agents/` | Agent subsystem — types, configuration, and orchestration for coding agents. |
| `server/src/agents/merge/` | Merge operations — rebases agent work onto master and runs post-merge validation. |
| `server/src/agents/merge/squash/` | Squash-merge orchestration: rebase agent work onto master and run post-merge gates. |
| `server/src/agents/pool/` | Agent pool — manages the set of active agents across all pipeline stages. |
| `server/src/agents/pool/auto_assign/` | Auto-assign submodules: wires focused sub-files and re-exports public items. |
| `server/src/agents/pool/auto_assign/watchdog/` | Watchdog task: detects orphaned agents, enforces turn/budget limits, and triggers auto-assign. |
| `server/src/agents/pool/auto_assign/watchdog/tests/` | Shared test helpers for the watchdog module. |
| `server/src/agents/pool/pipeline/` | Pipeline operations — stage advancement, completion handling, and merge orchestration. |
| `server/src/agents/pool/pipeline/advance/` | Pipeline advance — moves stories forward through pipeline stages after agent completion. |
| `server/src/agents/pool/pipeline/completion/` | Agent completion handling — processes exit results and triggers pipeline advancement. |
| `server/src/agents/pool/start/` | Agent start — spawns a new agent process in a worktree for a given story. |
| `server/src/agents/runtime/` | Agent runtimes — pluggable backends (Claude Code, Gemini, OpenAI) for running agents. |
| `server/src/chat/` | Transport abstraction for chat platforms.  The [`ChatTransport`] trait defines a platform-agnostic interface for sending and edit… |
| `server/src/chat/commands/` | Bot-level command registry shared by all chat transports.  Commands registered here are handled directly by the bot without invok… |
| `server/src/chat/transport/` | Chat transports — pluggable backends (Matrix, Slack, WhatsApp, Discord) for bot messaging. |
| `server/src/chat/transport/discord/` | Discord Bot integration.  Provides: - [`DiscordTransport`] — a [`ChatTransport`] that sends messages via the Discord REST API (`/… |
| `server/src/chat/transport/matrix/` | Matrix bot integration for Story Kit.  When a `.huskies/bot.toml` file is present with `enabled = true`, the server spawns a Matr… |
| `server/src/chat/transport/matrix/bot/` | Matrix bot — sub-modules for the Matrix chat bot implementation. |
| `server/src/chat/transport/matrix/bot/messages/` | Matrix message handler — processes incoming room messages and dispatches commands. |
| `server/src/chat/transport/matrix/config/` | Matrix transport configuration — deserialization of `bot.toml` Matrix settings. |
| `server/src/chat/transport/slack/` | Slack Bot API integration.  Provides: - [`SlackTransport`] — a [`ChatTransport`] that sends messages via the Slack Web API (`api.… |
| `server/src/chat/transport/slack/commands/` | Slack incoming message dispatch and slash command handling. |
| `server/src/chat/transport/whatsapp/` | WhatsApp Business API integration.  Provides: - [`WhatsAppTransport`] — a [`ChatTransport`] that sends messages via the Meta Grap… |
| `server/src/chat/transport/whatsapp/commands/` | WhatsApp command handling — processes incoming WhatsApp messages as bot commands. |
| `server/src/config/` | Project configuration — parses `project.toml` for agents, components, and server settings. |
| `server/src/crdt_snapshot/` | CRDT snapshot compaction with cross-node coordination.  This module implements full CRDT state snapshots for compacting the op jo… |
| `server/src/crdt_state/` | CRDT state layer — manages pipeline state as a conflict-free replicated document backed by SQLite.  The CRDT document is the prim… |
| `server/src/crdt_sync/` | CRDT sync — WebSocket-based replication of pipeline state between huskies nodes. WebSocket-based CRDT sync layer for replicating… |
| `server/src/crdt_sync/server/` | Server-side `/crdt-sync` WebSocket handler. |
| `server/src/db/` | SQLite storage layer — content store, shadow writes, and CRDT op persistence. |
| `server/src/http/` | HTTP server — module declarations for all REST, MCP, WebSocket, and SSE endpoints. |
| `server/src/http/agents/` | HTTP agent endpoints — thin adapters over `service::agents`.  Each handler: extracts payload → calls `service::agents::X` → shape… |
| `server/src/http/gateway/` | Gateway HTTP handlers — thin transport shells for the gateway service.  Each handler calls `service::gateway::*` for business log… |
| `server/src/http/mcp/` | HTTP MCP server module. |
| `server/src/http/mcp/agent_tools/` | MCP agent tools — start, stop, wait, list, and inspect agents via MCP. |
| `server/src/http/mcp/diagnostics/` | MCP diagnostic tools — server logs, CRDT dump, version, line counting, story movement. |
| `server/src/http/mcp/shell_tools/` | MCP shell tools — run commands, execute tests, and stream output via MCP.  This file is a thin adapter: it deserialises MCP paylo… |
| `server/src/http/mcp/story_tools/` | MCP story tools — create, update, move, and manage stories, bugs, refactors, and spikes via MCP.  This module is a thin adapter:… |
| `server/src/http/mcp/story_tools/story/` | Story creation, listing, update, and lifecycle MCP tools. |
| `server/src/http/mcp/tools_list/` | `tools/list` MCP method — returns the static schema for every tool the server exposes. |
| `server/src/http/workflow/` | Workflow helpers — shared story/bug file operations used by HTTP and MCP handlers. |
| `server/src/http/workflow/story_ops/` | Story operations — creates, updates, and manages acceptance criteria in story files. |
| `server/src/io/` | I/O subsystem — filesystem, shell, search, onboarding, and story metadata operations. |
| `server/src/io/fs/` | Filesystem I/O — module declarations and re-exports for file operations. |
| `server/src/io/fs/scaffold/` | Project scaffolding — creates the `.huskies/` directory structure and default files. |
| `server/src/io/fs/scaffold/detect/` | Stack detection — inspect the project root for marker files and emit TOML `[[component]]` entries plus `script/build\|lint\|test`… |
| `server/src/io/watcher/` | Filesystem watcher for `.huskies/project.toml` and `.huskies/agents.toml`.  Watches config files for changes and broadcasts a [`W… |
| `server/src/llm/` | LLM subsystem — chat orchestration, prompts, OAuth, and provider integrations. |
| `server/src/llm/chat/` | LLM chat — orchestrates multi-turn conversations with tool-calling LLM providers. |
| `server/src/llm/providers/` | LLM providers — module declarations for Anthropic, Claude Code, and Ollama backends. |
| `server/src/llm/providers/claude_code/` | Claude Code provider — runs Claude Code CLI in a PTY and parses structured output. |
| `server/src/pipeline_state/` | Typed pipeline state machine (story 520).  Replaces the stringly-typed CRDT views with strict Rust enums so that impossible state… |
| `server/src/service/` | Service layer — domain logic extracted from HTTP handlers.  Each sub-module follows the conventions documented in `docs/architect… |
| `server/src/service/agents/` | Agent service — public API for the agent domain.  This module orchestrates calls to `io.rs` (side effects) and the pure topic mod… |
| `server/src/service/anthropic/` | Anthropic service — public API for Anthropic API-key management and model listing.  Exposes functions to check, store, and use th… |
| `server/src/service/bot_command/` | Bot command service — domain logic for dispatching slash commands.  Extracted from `http/bot_command.rs` so that argument parsing… |
| `server/src/service/common/` | Shared pure helpers used by multiple service modules.  All sub-modules here are pure (no I/O, no side effects). Any helper that d… |
| `server/src/service/diagnostics/` | Diagnostics service — server logs, CRDT dump, permission management, and story movement.  Extracted from `http/mcp/diagnostics.rs… |
| `server/src/service/events/` | Events service — public API for the events domain.  This module re-exports the pure buffer types from `buffer.rs` and the side-ef… |
| `server/src/service/file_io/` | File I/O service — public API for filesystem and shell operations.  Exposes functions for reading, writing, and listing files sco… |
| `server/src/service/gateway/` | Gateway service — domain logic for the multi-project gateway.  Follows the conventions in `docs/architecture/service-modules.md`:… |
| `server/src/service/git_ops/` | Git operations service — worktree path validation and git command execution.  Extracted from `http/mcp/git_tools.rs` following th… |
| `server/src/service/merge/` | Merge service — domain logic for merging agent work to master.  Extracted from `http/mcp/merge_tools.rs` following the convention… |
| `server/src/service/notifications/` | Notifications service — pipeline-event fan-out to chat transports.  Subscribes to [`WatcherEvent`] broadcasts and posts human-rea… |
| `server/src/service/notifications/io/` | I/O side of the notifications service.  This is the **only** file inside `service/notifications/` that may perform side effects:… |
| `server/src/service/oauth/` | OAuth service — domain logic for the Anthropic OAuth 2.0 PKCE flow.  Extracts business logic from `http/oauth.rs` following the c… |
| `server/src/service/pipeline/` | Pipeline service — shared pipeline-domain logic.  Contains pure functions for parsing and aggregating pipeline status data. Used… |
| `server/src/service/project/` | Project service — public API for the project domain.  Exposes functions to open, close, query, and manage known projects. HTTP ha… |
| `server/src/service/qa/` | QA service — domain logic for requesting, approving, and rejecting QA reviews.  Extracted from `http/mcp/qa_tools.rs` following t… |
| `server/src/service/settings/` | Settings service — domain logic for project settings and editor configuration.  Extracts business logic from `http/settings.rs` f… |
| `server/src/service/shell/` | Shell service — command safety, path sandboxing, and output helpers.  Extracted from `http/mcp/shell_tools.rs` following the conv… |
| `server/src/service/status/` | Status broadcaster — unified pipeline-event fan-out for all consumers.  [`StatusBroadcaster`] lives on the [`crate::services::Ser… |
| `server/src/service/story/` | Story service — domain logic for creating, updating, and managing pipeline work items.  Extracted from `http/mcp/story_tools.rs`… |
| `server/src/service/timer/` | Timer service — deferred agent start via one-shot timers.  Provides [`TimerStore`] for persisting timers to `.huskies/timers.json… |
| `server/src/service/wizard/` | Wizard service — domain logic for the multi-step project setup wizard.  Follows the conventions from `docs/architecture/service-m… |
| `server/src/service/ws/` | WebSocket service — domain logic for real-time pipeline updates, chat, and permission prompts.  This module extracts the business… |
| `server/src/worktree/` | Git worktree management — creates, lists, and removes worktrees for agent isolation. |

### Crates

| Path | Purpose |
|------|---------|
| `crates/bft-json-crdt/benches/` |  |
| `crates/bft-json-crdt/bft-crdt-derive/src/` |  |
| `crates/bft-json-crdt/src/` |  |
| `crates/bft-json-crdt/tests/` |  |

### Frontend (`frontend/src/`)

| Path | Purpose |
|------|---------|
| `frontend/src/` |  |
| `frontend/src/api/` |  |
| `frontend/src/components/` |  |
| `frontend/src/components/selection/` |  |
| `frontend/src/hooks/` |  |
| `frontend/src/utils/` |  |

### Canonical patterns (copy these when adding new things)
- **New CRDT LWW-map collection:** see `server/src/crdt_state/lww_maps.rs`
- **New read-RPC handler:** register in `server/src/crdt_sync/rpc.rs`; call from frontend via `rpcCall<T>("method.name")` from `frontend/src/api/rpc.ts`
- **Migrate HTTP route → CRDT:** delete from `gateway.rs` / `http/*`, add op to `service/<area>/`, write through `crdt_state/`
- **New front-matter field:** add to `StoryMetadata` and `FrontMatter` in `io/story_metadata.rs` plus a `write_<name>_in_content` helper
- **New service module:** copy `service/agents/` structure (`mod.rs` + `io.rs` + `selection.rs`)
- **New chat command:** add a file under `chat/commands/` and register in `chat/commands/mod.rs::dispatch_command`
- **New auto-assigner predicate:** add to `agents/pool/auto_assign/story_checks.rs`, wire in `auto_assign/auto_assign.rs`
- **CRDT-seeding test helper:** `crate::db::write_item_with_content(story_id, stage, content)` — do not `fs::write` to `.huskies/work/{stage}/`


## Quality Gates
All enforced by `script/test`:
1. Frontend build (`npm run build`)
2. Rust formatting (`cargo fmt --all --check`)
3. Rust linting (`cargo clippy -- -D warnings`)
4. Rust tests (`cargo test`)
5. Frontend tests (`npm test`)