Developer Guide

Use this guide when working on this repository.

Read in order

  1. Invariants

  2. Architecture

  3. Security

  4. Code Style

  5. Release Process

Scope

These documents are aligned to contract.md and intentionally avoid project-external conventions.

Documentation Map

  • Reader guide — browsing and accessing documentation as an end-user.

  • Author guide — publishing documentation via the web UI.

  • Integrator guide — REST API, CI/CD uploads, and ACL management.

  • User guide — UI and API usage in production.

  • Operator guide — installation, environment variables, OIDC, and ACL management.

Testing Conventions

  • Every test function must have a docstring starting with “Ensure…” that describes the behaviour under test.

  • Test files should have a module-level docstring.

  • Run tests with task test:backend (requires uv and deps).

Coding Conventions

  • All functions must have a docstring.

    • Route handlers: Markdown docstring for API consumers, separated from internal notes by a line containing ---.

    • Internal Python code: Sphinx-style (:param:, :returns:, :raises:).

    • TypeScript: JSDoc style.

  • Every source file must have a module-level docstring.

  • Code must be fully type-annotated; avoid bare dict.

  • Maximum line length: 80 characters.

  • Environment variables use the DOCROOT_ prefix and are declared in app.settings.Settings.