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.
| Page | Answers |
|---|---|
| Setup | Toolchain versions, getting a clean clone green |
| Dev loop | Running both halves with live reload |
| Environments | Where to try a change, what each place proves, and the demo site |
| Demo content | The open content pack the public demo site plays: every item, its source and licence |
| Dev watchers | Watching the machine, your PRs and agent lanes; retiring worktrees cleanly |
| Testing | The test layers and which are gates |
| Playout bench | The cross-hardware playout measurement, its thresholds and CI jobs |
| CI | The jobs, path filters, and what’s required |
| Code hygiene | Finding unused code: the knip gate and the monthly Go deadcode report |
| Codegen | What’s generated and what’s committed |
| Commands | Every make target, generated: don’t hand-edit |
| AI in this project | Built with coding agents, and what that expects of a PR |
| Writing docs | Where a page goes, the page opener, style, diagrams and screenshots |
| Design | How 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
docs/design.mdis the source of truth. If code must deviate, update the doc in the same PR, first.- Gates are hard. Never weaken a selected local or CI gate to pass it. Use focused tests while
editing and
make verify BASE=origin/mainbefore pushing; reservemake verify SCOPE=allfor a deliberate complete-repository audit. - 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. - Tests never touch the network. Mock through
internal/testkit; extend it rather than writing a private mock. - 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 binarycmd/openapi/ exports api/openapi.yamlcmd/config-docs/ generates docs/reference/settings.mdcmd/dev-docs/ generates docs/reference/make.mdcmd/arch-docs/ generates the §2 package mapdocs/diagrams/ keeps D2 sources beside generated SVG diagramscmd/seed/ populates a dev store
internal/app/ wires every subsystem from an open storeinternal/api/ inbound HTTP — ServeMux + Huma v2internal/platform/store/ one interface, SQLite and Postgres behind itinternal/platform/settings/ the typed registry: env > database > defaultinternal/playout/ the streaming engineinternal/proposals/suggest/ intent → grounded proposalinternal/channels/schedule/ the scheduler domaininternal/filler/ clip catalog and pod assemblyinternal/testkit/ shared doubles and pinned fixtures
web/apps/web/ the SPA, built into internal/platform/web/dist and embeddedweb/packages/ tokens · api (orval) · core · fixturesdocs-site/ the docs site — renders docs/ in placedocs/design.md §14.2 has the full package map.