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)