Skip to content

Development

How Keryx is designed and built.

Where the specs live

Specs are not in this repository. They live in the project wiki, indexed on the Specs page with a number, title and status for each.

A spec is a point-in-time design record — written once, true of the moment it was written, read later for its conclusions. Documentation describes the software as it behaves today. Mixing the two made the docs harder to trust, so the specs moved out. Nothing in the reference, how-to, explanation or tutorial tiers should need a spec to be understood; if a page defers its reasoning to a spec number, that is a defect in the page.

New non-trivial work still starts with a spec — claim the next number on the wiki, draft against the canonical shape, then implement. The lifecycle is in AGENTS.md.

Ways of working

  • TDD + BDD. Unit-test the deterministic core; godog .feature scenarios for user-facing workflows. Providers and ffmpeg are faked behind interfaces, so the timing maths, text wrapping, theme resolution and posting ledger are tested with no network, no binary and no API key. → Testing
  • Conventional Commits, colophon cuts releases; no AI attribution.
  • Quality at the MR gate via the phpboyscout/cicd components.

UI mockup

A clickable, non-functional prototype of the studio, built to surface gaps in the web-UI contract before implementation: mockups/studio/index.html.

Reference implementation

The blog's scripts/gen-*.py are the parity reference for generation behaviour; the Go port reproduces them deliberately. That is why several defaults are odd numbers rather than round ones — the 0.4 s crossfade, the 0.5 s lead and the 0.7 s tail are the values the scripts used, kept so a ported reel matches a scripted one frame for frame.