Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
68 lines (58 loc) · 3.33 KB

ARCHITECTURE.md

File metadata and controls

68 lines (58 loc) · 3.33 KB

Foolery Architecture

Keyboard-first browser control room for orchestrating multi-agent software work across repositories.

Data / Control Flow

Browser (React/Zustand/TanStack Query)
  ↓ fetch()
Next.js API Routes (/api/beats, /api/terminal, /api/orchestration, ...)
  ↓ getBackend()
BackendPort interface (abstract)
  ↓ AutoRoutingBackend resolves per-repo
Concrete backend (KnotsBackend | BeadsBackend | BdCliBackend)
  ↓ Bun.spawn()
Memory manager CLI (kno | bd)
  ↓ reads/writes
Git-tracked beat data (.knots/ or .beads/)

Session flow: user clicks Take!/Scene! → createSession() builds prompt → selectFromPool() picks agent → Bun.spawn(agent_command) → SSE stream to xterm in browser → agent completes → workflow state advances.

Directory Map

Path Purpose
src/app/ Next.js App Router — pages and API routes
src/app/api/ REST API (beats, terminal, orchestration, settings, doctor)
src/components/ React components (beat table, terminal, agent history, settings)
src/components/ui/ shadcn/ui primitives
src/hooks/ Custom React hooks
src/stores/ Zustand stores (app, terminal, notification)
src/lib/ Core business logic — types, backends, workflows, sessions
src/lib/backends/ BackendPort implementations (Knots, Beads, CLI, Stub)
src/lib/__tests__/ Unit tests (Vitest)
src/lib/openapi/ OpenAPI 3.1.0 spec generation
src/stories/ Storybook stories
scripts/ Build, install, release, and setup scripts
docs/ Project documentation and ADRs

Key Entry Points

  • Backend factory: src/lib/backend-factory.ts — createBackend(), AutoRoutingBackend
  • Backend interface: src/lib/backend-port.ts — BackendPort (all backends implement this)
  • Execution backend: src/lib/execution-backend.ts — StructuredExecutionBackend (lease/iteration/snapshot lifecycle)
  • Session lifecycle: src/lib/terminal-manager.ts — createSession(), abortSession()
  • Orchestration: src/lib/orchestration-manager.ts — createOrchestrationSession()
  • Agent dispatch: src/lib/agent-pool.ts — selectFromPool()
  • Workflows: src/lib/workflows.ts — step definitions, state mappings
  • Registry: src/lib/registry.ts — loadRegistry(), addRepo(), removeRepo()
  • Diagnostics: src/lib/doctor.ts — runDoctor(), runDoctorFix()
  • Client API: src/lib/api.ts — browser-side fetch wrappers
  • Domain types: src/lib/types.ts — Beat, TerminalSession, Wave, MemoryWorkflowDescriptor
  • Validation: src/lib/schemas.ts — Zod schemas for all inputs

Build System

Command Purpose
bun install Install dependencies
bun run dev Dev server (localhost:3000)
bun run build Production build
bun run lint ESLint (errors on size violations)
bunx tsc --noEmit Type check
bun run test Vitest unit tests
bun run storybook Component dev (localhost:6006)