Glyphin

Database-as-source-of-truth curriculum pipeline

• Curriculum lives in Postgres and is published into a versioned delivery.* catalog carrying a publicationId and publicationCacheKey, which define the cache and version boundary for public lesson content.
• A prebuild step (publication:generate) bakes the active publication into a generated lesson artifact so prerendered lesson HTML always matches a known content version.
• An ESLint no-restricted-imports rule blocks app code from importing the authoring source ($lib/data/thai) directly — everything must go through the published delivery catalog, with the data and server layers as the only exceptions.
• Dedicated scripts separate "refresh content but keep my auth/learner data" (db:content:refresh) from a full local reset, which keeps day-to-day curriculum iteration cheap.

Security boundary designed before the auth feature shipped

• Supabase is server-only: no browser client ships, so connect-src stays at 'self' and the browser talks exclusively to app-owned SvelteKit endpoints.
• CSP is configured with mode: "auto" so SvelteKit emits SHA-256 hashes for prerendered pages (delivered via <meta>) and per-request nonces for SSR routes like /auth; the one inline theme script was deliberately extracted to a static file rather than allowing unsafe-inline for scripts.
• Auth uses email OTP with @supabase/ssr request-scoped clients, getUser() for every trust decision (never cookie-derived sessions), and Cloudflare Turnstile allow-listed in script-src/frame-src.
• SvelteKit's built-in CSRF origin check is documented as load-bearing for the /api/learner/sync endpoint, with guard comments at both the config and the route.

Local-first learner state with server reconciliation

• Anonymous progress persists to localStorage so the learner shell renders instantly and works offline; authenticated learner data arrives as a projection that overlays prerendered lesson pages instead of forcing them back to per-user HTML.
• Local progress is treated as untrusted input at sign-in — merging into the account happens through a validated, idempotent, course-version-aware server path.
• Row-level security is treated as a last line of defence rather than the primary contract; all learner writes go through server-owned routes.

Script-agnostic lesson contract

• The data model encodes a strict two-phase lesson (learning → scored practice checkpoint) with typed anchor words, graphemes, rules, drills, and review sets; components render the contract rather than inventing lesson-specific shapes.
• DTOs deliberately use neutral names (course, text, segments, graphemes) so the same engine can host other writing systems — 60+ candidate curricula (Hangul, Devanagari, Hebrew, Cherokee, cuneiform, Braille) are already scoped in the authoring notes.
• Offline authoring CLIs (curriculum:scaffold, validate, score, review) plus Python corpus/frequency analysis tooling support building new courses on frequency-first sequencing rather than alphabet order.

Two-project test setup and a strict quality gate

• Vitest runs two isolated projects: a node project for server trust boundaries, utils, and curriculum-mapping logic, and a jsdom project using @testing-library/svelte for real component rendering and the localStorage progress store. They're deliberately kept apart so browser resolve conditions never leak into how @supabase/ssr resolves on the server.
• A single quality:check command chains tests, Prettier, markdownlint, ESLint 10 flat config, Stylelint, and type-checking; Husky + lint-staged run the fast subset pre-commit.
• The GitHub Actions workflow runs each check independently after install so one push surfaces every failure at once, with concurrency cancellation on superseded runs and Dependabot plus Knip covering dependency hygiene.

Documentation as an architectural constraint

• The repo enforces a hard split: durable reference docs (auth architecture, DB schema contract, SEO/indexing contracts, learning philosophy) live in docs/, while dated plans and task trackers live in .ai/ — with an explicit test ("if it has checkboxes or a status line, it's a plan").
• Agent- and Copilot-facing instruction files (.github/instructions/*.instructions.md) encode per-area conventions for routes, components, API handlers, data/state, and lesson flow, so tooling-assisted changes stay inside the same boundaries as hand-written ones.