Developer guide¶

For anyone changing the code, people and coding agents alike. The operator guide covers running a server and the user guide covers the screens; this section covers how the code is put together and how to work on it without breaking what is there.

AGENTS.md in the repository root is the short version: commands, conventions and where things live, written for a coding agent. The pages here are the long version.

Start here¶

• Set up a development environment: install, run the server and the worker, run the tests, lint.
• Architecture: the apps and how they relate, the Practice shell and the matter workspace, how an HTMX page is composed, where state lives, where background work runs.

Conventions¶

How things are done in this codebase, with the reasons.

• HTMX, Alpine and idiomorph: partial swaps, triggers, modals, confirmations, toasts, and the CSS rules.
• Session state: filters, selections, pagination and sort keys held in the session, and how a bad value is kept from crashing a list.
• Testing: the test database, fixtures, parallel runs, faking external services, and what to run when.
• Branches and releases: topical branches, pull requests into dev, migrations, what a deploy does.
• CSS theming: the seven themes, tokens versus scoped rules, and where dark-mode structure lives.
• Writing documentation: how this site is organised and the house rules for adding to it.
• Squashing migrations: the steps after a squash.

Subsystems¶

One page per part of the system, each with the same shape: where the code is, the data model, how the main flows work, background work, access, and the things that bite.

Decisions¶

Design choices that would otherwise have to be rediscovered are recorded under Decisions. Read the record before rebuilding something that was retired on purpose.