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

Core

File	Description
server/src/main.rs	Entry point, CLI argument parsing, and server startup
server/src/config.rs	Parses project.toml for agents, components, and server settings
server/src/state.rs	Global mutable session state (project root, cancellation)
server/src/store.rs	JSON-backed persistent key-value store for settings
server/src/gateway.rs	Multi-project gateway mode (MCP proxy, project switching, agent registration)

Agents

File	Description
server/src/agents/mod.rs	Types, configuration, and orchestration for coding agents
server/src/agents/gates.rs	Runs test suites and validation scripts in agent worktrees
server/src/agents/lifecycle.rs	File creation, archival, and stage transitions for pipeline items
server/src/agents/merge.rs	Rebases agent work onto master and runs post-merge validation
server/src/agents/pty.rs	Spawns agent processes in pseudo-terminals and streams output
server/src/agents/token_usage.rs	Persists per-agent token consumption records to disk
server/src/agent_log.rs	Reads and writes JSONL agent event logs to disk
server/src/agent_mode.rs	Headless build-agent mode for distributed story processing

Agent Pool

File	Description
server/src/agents/pool/mod.rs	Manages the set of active agents across all pipeline stages
server/src/agents/pool/start.rs	Spawns a new agent process in a worktree for a story
server/src/agents/pool/stop.rs	Terminates a running agent while preserving its worktree
server/src/agents/pool/pipeline/advance.rs	Moves stories forward through pipeline stages
server/src/agents/pool/pipeline/completion.rs	Processes exit results and triggers pipeline advancement
server/src/agents/pool/pipeline/merge.rs	Orchestrates the merge-to-master flow for completed stories
server/src/agents/pool/auto_assign/auto_assign.rs	Scans pipeline stages and dispatches agents to unassigned stories

CRDT & Database

File	Description
server/src/crdt_state.rs	Pipeline state as a conflict-free replicated document backed by SQLite
server/src/crdt_sync.rs	WebSocket-based replication of pipeline state between nodes
server/src/pipeline_state.rs	Typed pipeline state machine
server/src/db/mod.rs	Content store, shadow writes, and CRDT op persistence

HTTP — MCP Tools (the tools agents call)

File	Description
server/src/http/mcp/mod.rs	MCP endpoint dispatching tool calls
server/src/http/mcp/agent_tools.rs	Start, stop, wait, list, and inspect agents
server/src/http/mcp/git_tools.rs	Status, diff, add, commit, and log on agent worktrees
server/src/http/mcp/merge_tools.rs	Merge agent work to master and report failures
server/src/http/mcp/shell_tools.rs	Run commands, execute tests, and stream output
server/src/http/mcp/story_tools.rs	Create, update, move, and manage stories/bugs/refactors
server/src/http/mcp/diagnostics.rs	Server logs, CRDT dump, version, and story movement helpers

Chat — Bot Commands

File	Description
server/src/chat/commands/mod.rs	Bot-level command registry shared by all transports
server/src/chat/commands/status.rs	status command and pipeline status helpers
server/src/chat/commands/backlog.rs	backlog command — shows only backlog-stage items
server/src/chat/commands/run_tests.rs	run_tests command — run the project's test suite

Chat — Transports

File	Description
server/src/chat/transport/matrix/	Matrix bot integration
server/src/chat/transport/slack/	Slack bot integration
server/src/chat/transport/whatsapp/	WhatsApp Business API integration
server/src/chat/transport/discord/	Discord bot integration

Frontend

Directory	Description
frontend/src/components/	React UI components
frontend/src/api/	API client code (gateway, agents, etc.)

Utilities

File	Description
server/src/rebuild.rs	Server rebuild and restart logic
server/src/worktree.rs	Creates, lists, and removes git worktrees for agent isolation
server/src/io/watcher.rs	Filesystem watcher for .huskies/work/ and project.toml

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)