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

### Backend roots
| Path | Purpose |
|------|---------|
| `server/src/main.rs` | Binary entry; CLI parsing; server startup |
| `server/src/config/` | `project.toml` parsing |
| `server/src/state.rs` | Global mutable session state |
| `server/src/store.rs` | JSON-backed KV store for settings |
| `server/src/gateway.rs` | Multi-project gateway mode (route builder, MCP proxy) |
| `server/src/agent_mode.rs` | Headless build-agent mode |
| `server/src/services.rs` | Top-level service registry / wiring |
| `server/src/workflow.rs` | Cross-cutting workflow helpers |

### Agents
| Path | Purpose |
|------|---------|
| `server/src/agents/mod.rs` | Agent types and orchestration root |
| `server/src/agents/pool/` | Coder/QA/mergemaster pool, auto-assign, lifecycle, retry |
| `server/src/agents/pool/auto_assign/` | Auto-assigner: scans pipeline, spawns agents on free slots |
| `server/src/agents/pool/pipeline/` | Stage transitions, completion, merge orchestration |
| `server/src/agents/runtime/` | Per-provider runtimes: `claude_code.rs`, `gemini.rs`, `openai.rs` |
| `server/src/agents/merge/` | Squash-merge mechanics, conflict detection |
| `server/src/agents/pty.rs` | PTY pseudo-terminal spawning + output streaming |
| `server/src/agents/lifecycle.rs` | Stage transitions and item movement |
| `server/src/agents/gates.rs` | Quality-gate runner |
| `server/src/agents/session_store.rs` | Per-agent session history |
| `server/src/agents/token_usage.rs` | Per-agent token cost ledger |

### CRDT + persistence
| Path | Purpose |
|------|---------|
| `server/src/crdt_state/` | CRDT primitives — `lww_maps.rs`, `state.rs`, `read.rs`, `write.rs`, `ops.rs`, `types.rs`, `presence.rs`, `gateway_config.rs` |
| `server/src/crdt_sync/` | WebSocket replication; `rpc.rs` holds the **read-RPC registry** |
| `server/src/crdt_sync/server/` | Sync-server endpoint, keepalive |
| `server/src/crdt_snapshot/` | Snapshot persistence |
| `server/src/pipeline_state/` | Typed pipeline state machine + projections |
| `server/src/db/mod.rs` | `content_store`, shadow writes, op persistence |

### HTTP / WS routes
| Path | Purpose |
|------|---------|
| `server/src/http/mod.rs` | Top-level route registration |
| `server/src/http/ws.rs` | Top-level WebSocket dispatcher |
| `server/src/http/events.rs` | Event push endpoint |
| `server/src/http/agents/` | Agent REST + tests |
| `server/src/http/gateway/` | Gateway routes — `rest.rs`, `websocket.rs`, `mcp.rs`, `jsonrpc.rs` |
| `server/src/http/mcp/` | MCP tool handlers (agent_tools, story_tools, merge_tools, qa_tools, status_tools, git_tools, wizard_tools, dispatch.rs) |
| `server/src/http/workflow/` | Story-creation workflow endpoints (`bug_ops.rs`, `test_results.rs`) |
| `server/src/http/anthropic.rs` | Anthropic API proxy |
| `server/src/http/oauth.rs` | OAuth flows |
| `server/src/http/bot_command.rs` | Bot command dispatch |
| `server/src/http/bot_config.rs` | Bot config save/get |
| `server/src/http/wizard.rs` | Setup wizard endpoint |

### Chat (bot)
| Path | Purpose |
|------|---------|
| `server/src/chat/mod.rs` | Chat module root |
| `server/src/chat/commands/` | Slash commands — `status.rs`, `backlog.rs`, `run_tests.rs`, `depends.rs`, `freeze.rs`, `unblock.rs`, `move_story.rs`, `assign.rs`, `loc.rs`, `cost.rs`, `help.rs`, etc. |
| `server/src/chat/commands/mod.rs` | Command dispatch |
| `server/src/chat/transport/matrix/` | Matrix bot |
| `server/src/chat/transport/slack/` | Slack bot |
| `server/src/chat/transport/whatsapp/` | WhatsApp Business API |
| `server/src/chat/transport/discord/` | Discord bot |
| `server/src/chat/test_helpers.rs` | `write_item_with_content` and other CRDT-seeding test helpers |

### Domain services (one folder per concern)
| Path | Purpose |
|------|---------|
| `server/src/service/agents/` | Agent listing + selection |
| `server/src/service/events/` | Event store + buffer |
| `server/src/service/gateway/` | Gateway business logic |
| `server/src/service/git_ops/` | git status/diff/add/commit primitives |
| `server/src/service/merge/` | Merge orchestration |
| `server/src/service/notifications/` | Notification dispatch |
| `server/src/service/qa/` | QA lifecycle |
| `server/src/service/story/` | Story CRUD + front matter |
| `server/src/service/timer/` | Timer schedule |
| `server/src/service/wizard/` | Setup wizard state machine |
| `server/src/service/ws/` | WebSocket message dispatch + inbound RPC routing |
| `server/src/service/oauth/` | OAuth flow + PKCE |
| `server/src/service/file_io/` | Filesystem read/write helpers |
| `server/src/service/shell/` | Shell command execution + path-guard |
| `server/src/service/anthropic/` | Anthropic API client |
| `server/src/service/bot_command/` | Bot command core logic |
| `server/src/service/diagnostics/` | Server diagnostics |
| `server/src/service/pipeline/` | Pipeline-level service helpers |
| `server/src/service/project/` | Project loading and selection |
| `server/src/service/settings/` | Settings persistence + validation |
| `server/src/service/status/` | Status text formatting |
| `server/src/service/common/` | Cross-cutting service helpers |

### LLM
| Path | Purpose |
|------|---------|
| `server/src/llm/providers/` | `anthropic.rs`, `ollama.rs` |
| `server/src/llm/chat/` | LLM chat session (`run.rs`, `tools.rs`) |
| `server/src/llm/oauth.rs` | LLM OAuth flow |
| `server/src/llm/prompts.rs` | Prompt templates |

### IO, watcher, worktrees
| Path | Purpose |
|------|---------|
| `server/src/io/fs/` | Project file paths + scaffold |
| `server/src/io/watcher/` | Filesystem watcher for `.huskies/work/` and `project.toml` |
| `server/src/io/story_metadata.rs` | Story front-matter parsing/writing — `parse_front_matter`, `set_front_matter_field`, `write_*_in_content` setters |
| `server/src/io/onboarding.rs` | First-run onboarding |
| `server/src/io/wizard.rs` | Wizard IO |
| `server/src/io/search.rs` | Repo search |
| `server/src/io/test_helpers.rs` | Generic IO test helpers |
| `server/src/worktree/` | Git worktree create/remove + git ops |

### Utilities
| Path | Purpose |
|------|---------|
| `server/src/rebuild.rs` | Server rebuild + restart |
| `server/src/agent_log.rs` | JSONL agent event logs |
| `server/src/log_buffer.rs` | In-memory log buffer |
| `server/src/mesh.rs` | Mesh networking |
| `server/src/node_identity.rs` | Node identity |
| `server/src/gateway_relay.rs` | Gateway relay |

### Frontend
| Path | Purpose |
|------|---------|
| `frontend/src/api/rpc.ts` | **Shared read-RPC client** over `/ws` — `rpcCall<T>(method, params)` |
| `frontend/src/api/agents.ts` | Agent listing + streaming (uses `rpcCall`) |
| `frontend/src/api/gateway.ts` | Multi-project gateway client |
| `frontend/src/api/client.ts` | HTTP client base |
| `frontend/src/components/` | React UI components (Chat, AgentPanel, WorkItemDetailPanel, etc.) |
| `frontend/src/components/selection/` | Selection-related components |
| `frontend/src/hooks/` | React hooks (`useChatWebSocket`, etc.) |
| `frontend/src/utils/` | Utility helpers |

### Crates
| Path | Purpose |
|------|---------|
| `crates/bft-json-crdt/src/` | Core CRDT library — JSON CRDT, lists, maps, registers |
| `crates/bft-json-crdt/bft-crdt-derive/src/` | Derive macros |

### Canonical examples (when adding new things, copy these patterns)
- **New CRDT collection (LWW-map):** see `server/src/crdt_state/lww_maps.rs`
- **New read-RPC handler:** register in `server/src/crdt_sync/rpc.rs` (e.g. `handle_active_agents_list`); call from frontend with `rpcCall("method.name")`
- **Migrate HTTP route → CRDT op:** delete the route from `gateway.rs` / `http/*`, add operation 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 structure of `server/src/service/agents/` (`mod.rs` + `io.rs` + `selection.rs`)
- **New chat command:** add file under `server/src/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`
- **Test setup with CRDT seeding:** use `crate::db::write_item_with_content(story_id, stage, content)` — never `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`)