Skip to content

Developing Loomarr

For: anyone changing Loomarr’s code or docs. You’ll get: where to start, and a map of the contributor pages.

This directory is the single source for how to build, run and test Loomarr. README.md, CONTRIBUTING.md, and agent-specific adapters link here. AGENTS.md keeps the concise cross-harness contract and points here for detail.

PageAnswers
SetupToolchain versions, getting a clean clone green
Dev loopRunning both halves with live reload
EnvironmentsWhere to try a change, what each place proves, and the demo site
Demo contentThe open content pack the public demo site plays: every item, its source and licence
Dev watchersWatching the machine, your PRs and agent lanes; retiring worktrees cleanly
TestingThe test layers and which are gates
Playout benchThe cross-hardware playout measurement, its thresholds and CI jobs
CIThe jobs, path filters, and what’s required
Code hygieneFinding unused code: the knip gate and the monthly Go deadcode report
CodegenWhat’s generated and what’s committed
CommandsEvery make target, generated: don’t hand-edit
AI in this projectBuilt with coding agents, and what that expects of a PR
Writing docsWhere a page goes, the page opener, style, diagrams and screenshots
DesignHow the system works, and why (owned by the design docs, #779)

Agent contracts (sessions, claims, worktrees, skills) live beside the agent config in docs/agents/, off the site. Maintainer runbooks, plans and evidence live in project/.

The rules that matter

  1. docs/design.md is the source of truth. If code must deviate, update the doc in the same PR, first.
  2. Gates are hard. Never weaken a selected local or CI gate to pass it. Use focused tests while editing and make verify BASE=origin/main before pushing; reserve make verify SCOPE=all for a deliberate complete-repository audit.
  3. Generated files are never hand-edited — api/openapi.yaml, docs/reference/settings.md, docs/reference/make.md, the orval client, token artifacts. Migrations are forward-only.
  4. Tests never touch the network. Mock through internal/testkit; extend it rather than writing a private mock.
  5. Application code is Go. Exceptions: the frontend, the vendored binaries invoked via exec, and build tooling like Storybook and the docs site.

New dependencies are fine when they earn their place — add a row to docs/design.md §14 in the same PR.

Where the code lives

cmd/loomarr/ the binary
cmd/openapi/ exports api/openapi.yaml
cmd/config-docs/ generates docs/reference/settings.md
cmd/dev-docs/ generates docs/reference/make.md
cmd/arch-docs/ generates the §2 package map
docs/diagrams/ keeps D2 sources beside generated SVG diagrams
cmd/seed/ populates a dev store
internal/app/ wires every subsystem from an open store
internal/api/ inbound HTTP — ServeMux + Huma v2
internal/platform/store/ one interface, SQLite and Postgres behind it
internal/platform/settings/ the typed registry: env > database > default
internal/playout/ the streaming engine
internal/proposals/suggest/ intent → grounded proposal
internal/channels/schedule/ the scheduler domain
internal/filler/ clip catalog and pod assembly
internal/testkit/ shared doubles and pinned fixtures
web/apps/web/ the SPA, built into internal/platform/web/dist and embedded
web/packages/ tokens · api (orval) · core · fixtures
docs-site/ the docs site — renders docs/ in place

docs/design.md §14.2 has the full package map.