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)