Skip to content
GitHub

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

  1. One continuous single-page, step-by-step wizard — never multi-page
  2. Pure scoring engine per form (types → rules → grader → flagged issues), independently testable
  3. Both stacks — HTML/headless and SvelteKit — implemented per form, each covering the questionnaire and its dashboard, both on the Lily Design System
  4. 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; null for 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, and deleted_at timestamps on every table
  • Generated artefacts (XML, FHIR, protobuf, OpenAPI, the Axum setup script, CHANGELOG.md, examples/) are never hand-edited — regenerated from source instead