Architecture
How each form project is laid out and the design patterns shared across them.
Directory layout
Each form lives in forms/<slug>/ with a consistent layout:
forms/<slug>/
index.md # Form description and scoring details
README.md -> index.md # Symlink for GitHub rendering
AGENTS.md # Agent instructions for this form
CLAUDE.md # Claude Code project instructions
spec/ # Living domain spec (index.md + README symlink)
plan.md # Implementation plan and status
tasks.md # Task tracking
CHANGELOG.md # Keep-a-Changelog + SemVer
doc/ # Clinical/regulatory reference documentation
examples/ # Filled-form JSON fixtures + personas + FHIR R5 Bundle
sql/ # PostgreSQL Liquibase migrations (source of truth)
xml/ # XML + DTD per SQL table entity (generated)
fhir/r5/ # FHIR HL7 R5 JSON per SQL entity (generated)
protobuf/ # Protocol Buffers .proto schemas per SQL entity (generated)
openapi/ # OpenAPI 3.1 .yaml specifications per SQL entity (generated)
front-end-with-html/ # Questionnaire + dashboard (HTML, Lily Design System)
front-end-with-svelte/ # Questionnaire + dashboard (SvelteKit, Lily Design System)
back-end-with-axum/ # Back-end Rust JSON API (axum + axa + sqlx)
back-end-with-axum-setup # Scaffold generator (generated) Design patterns
Front-ends
- One continuous single-page, step-by-step wizard — never multi-page
- Pure scoring engine per form (types → rules → grader → flagged issues), independently testable
- Both stacks — HTML/headless and SvelteKit — implemented per form, each covering the questionnaire and its dashboard, both on the Lily Design System
- Header carries theme, locale, text-size, and share controls, wired to the vendored Lily Design System Svelte/HTML helpers
Back-end
- Rust JSON API — axum routing via the Axum framework, no server-rendered templates
- Relational, per-table schema: one Axum migration + one entity + one RESTful scaffold controller per SQL table (never a single table with a JSONB blob)
serde(rename_all = "camelCase")on every struct shared with a front-end, mirroring the front-end's TypeScript types- sqlx entities against PostgreSQL, generated from the same
sql/migrations that are the schema's source of truth - Postgres-only background queue, structured logs, and health endpoints
Conventions
- Empty string
''for unanswered text/enum fields;nullfor unanswered numeric, date, and time fields - camelCase property names in TypeScript and front-end Rust serde; snake_case in SQL and Rust internals
- Step components named
StepNName.svelte(1-indexed; no spaces, ampersands, or parentheses) - UI components in
src/lib/components/ui/ - UUIDv4 primary keys via
gen_random_uuid();created_at,updated_at, anddeleted_attimestamps on every table - Generated artefacts (XML, FHIR, protobuf, OpenAPI, the Axum setup script,
CHANGELOG.md,examples/) are never hand-edited — regenerated from source instead