Pattern Library — Docs - v10r

Foundations

Architecture & Request Pipeline

Multi-client core (hexagonal domain modules) deep: One backend operations layer (#lib/server/[domain]/) serves four clients — human UI, AI tools, REST API, background jobs — via thin wrappers, with zero duplicated business logic.
Runtime layers & request flow (7-layer view): Documents v10r's seven-layer abstraction hierarchy, from tech stack down to code, anchored by the hooks.server.ts composition root and the hexagonal domain core.
Codebase map ("where does X live"): Provides a spatial quick-reference table mapping each kind of code (business logic, route adapters, schemas, components, state) to its canonical directory.
Middleware / 14-stage hook chain (CSRF, headers, guards): Describes the ordered SvelteKit hook chain in src/hooks.server.ts — security headers, i18n, auth, CSRF, session, consent, and guards — as the single source of truth for request interception.
REST API patterns (pagination, envelopes, rate limits): Defines the file-based +server.ts convention for REST endpoints, covering Valibot validation, error() status codes, pagination, and response envelopes.
Error handling (expected/unexpected/form/API): Classifies errors into expected, unexpected, form, and API categories, each handled by a distinct SvelteKit mechanism (error(), handleError, fail(), Response.json()).
State management (Svelte 5 runes): Establishes v10r's rune-based state strategy — $state/$derived for component state, .svelte.ts modules or the Context API for shared state, with an SSR-safety rule against module-level state leaking across requests.
Request-cycle visualizer (form · API · AI): An interactive showcase that visualizes the full form, REST API, and AI request cycles as they pass through the hooks chain and domain layers.
Deployment (Vercel serverless, container target planned): Covers the deployment setup — Vercel Node.js serverless is the one wired target (adapter-vercel hardcoded); a Bun container target (Koyeb) is a planned portability goal the job system and env parity already accommodate.
Testing infrastructure (Vitest, PGlite isolation): Two vitest lanes over one config: a fast `unit` lane and a `db` lane whose files restore a PGlite datadir snapshot built once per run, plus the source-scanning gate tests that ratchet architectural and naming invariants.
Pattern MCP (agent-queryable pattern registry, local stdio): A read-only local stdio MCP server that exposes v10r's curated pattern registry (docs, code, tests, invariants) to coding agents so they can emulate patterns instead of grepping.
Hosted MCP (two trust surfaces: public read-only · bearer admin): Serves the pattern registry and a separate demo-state service over HTTP through distinct trust boundaries — an unauthenticated public endpoint and bearer-token-protected private/admin endpoints.
Rust→wasm compute kernel (vendored, plugin-free): Rust crate compiled to wasm in an ephemeral container, artifacts vendored into src/lib/wasm/kernel/, loaded via ?url + explicit init with zero Vite plugins, benchmarked honestly against a line-for-line JS twin with a vitest parity gate.
External service runtime (a separately deployed backend behind a typed client) deep: A separately deployed service — reference: the Rust/Axum runtime lab, an order-rules engine, in its own OCI container — is reached only through one server-only service client: a code-generated OpenAPI contract with generated TS types and drift-checked runtime mirrors, service-enforced bearer auth, request deadlines, one failure kind per cause, request ids and a Server-Timing split. Hardened by measurement: non-blocking stdout logging, SERVICE_TOKEN_PREVIOUS rotation, a 16 KiB head cap, a contract release record with skew diagnosis, cargo-deny, and a 0.1 CPU benchmark profile. Verified locally (container, real client, showcase, controlled lab) and in production on Render Free Frankfurt (end to end, failure paths measured); hosted cold-start and warm percentiles are still unmeasured.
URL state (one typed spec for search params, navigate vs shallow writes) deep: Search params are read and written through one typed spec shared by loads and components — invalid input falls back instead of throwing, defaults never reach the URL, foreign params survive — and every write picks navigate (goto, the load re-runs) or shallow (replaceState from $app/navigation, no load, no navigation hooks), never raw history.

App Shell & Navigation

Shell layout (no global header, sidebar-first): Defines the app shell's structural layout — a collapsible sidebar for primary navigation, a main content area, and a persistent footer, with no global header.
Responsive sidebar (rail / drawer / FAB): Implements an asymmetric responsive sidebar — a persistent hover-expanding rail on desktop and an off-canvas thumb-accessible drawer on mobile, triggered by a FAB.
Navigation structure & progressive disclosure: Structures nav items as compound split buttons — a primary click zone that navigates and a dropdown zone that progressively reveals subpages or section anchors.
Keyboard shortcuts registry + help modal: A central registry of global, navigation, and contextual keyboard shortcuts (e.g. Cmd+K for search, ? for help) surfaced through a discoverable help modal.
Modals & layer stack: Manages a stacked layer of modals and dialogs (quick search, shortcuts help, session expiry) through a shared state module and dialog primitives.
Toasts (stacking, undo): Ephemeral, stacking feedback messages (success/error/warning/info) shown in response to user-initiated actions, distinct from the persistent notification center.
Session lifecycle UI (expiry, re-auth): Shell-level UI that reacts to authentication session state — showing an expiry warning, a re-authentication modal on expiry, and immediate redirect on revocation.
Settings (theme cookie, language, a11y): A settings hub page covering appearance (theme cookie), language, privacy toggles, and accessibility preferences, backed by a load/save form action.
Style randomizer (theme × typography × palette): Randomizes decorative styling (typography pairing and color palette) on each visit from pre-validated, WCAG-compliant sets, kept orthogonal to the user's dark/light theme choice.
Loading states (skeletons, nav progress): Defines visual feedback for initial load, navigation, data fetch, action, and streaming states using skeleton screens and a navigation progress bar.
Empty states: Standardizes the anatomy (icon, title, description, action) for UI shown when there is no data — first-run, zero search results, deleted content, or error recovery.
Page header (per-page, XSS-safe): A per-page header component (breadcrumbs, title, actions) rendered inside the main content area instead of a global header, keeping page-specific chrome scoped and safe against XSS.
Quick Search / command palette (two-lane FTS): A universal search combining an instant client-side lane with a debounced server-side full-text-search lane, surfaced via a Cmd+K command palette and a dedicated /search page.

UI Components & Design System

Component-first UI system (primitives/composites/layout, CVA, tokens) deep: A layered component system — Bits UI → primitives (styled atoms) → composites (business logic) → layout (structural wrappers) — styled entirely through CVA → UnoCSS → design-token CSS variables.
Design philosophy & three-tier theming: Five content-first, accessibility-driven design principles paired with a three-tier token system (primitives → semantic tokens → component usage) flowing from src/app.css through tokens.ts into UnoCSS.
Explosive Discovery — nested depth for dense menus and pages deep: A review heuristic, not a rule: when a menu, toolbar or page offers more than ~5 ± 2 simultaneous choices, structure capability as directions that narrow intent (Overview → Direction → Context → Action → Detail), promote actions by context, keep an expert path beside every discovery path, and project one semantic hierarchy per device. The desk's panel menus embody it: one composed array rendered as desktop sub-menus and as a flat mobile sheet, with shortcuts declared on the same items.
Design tokens (breakpoints, fluid type/space, z-index): Centralizes breakpoints, fluid typography/spacing clamp() scales, and z-index values in a single tokens.ts file consumed by the UnoCSS theme so no component hardcodes design values.
Tonal (surface) elevation engine: A pure, SSR-safe TypeScript engine that computes each surface's relative depth (parent level + 1) via Svelte context and stamps it as a data-elevation attribute, decoupled from z-index.
Primitives (~40 Bits UI wrappers): Roughly 40 styled atomic components (Button, Input, Badge, Select, Table, etc.) that wrap Bits UI headless primitives with CVA variants and design tokens.
Composites: Higher-level components (Card, FormField, CommandPalette, Chatbot, Dock, etc.) composed from primitives that add business logic and feature behavior.
Layout primitives (Stack, Cluster, Surface): Structural wrapper components (Stack, Cluster, Surface, PageContainer) that provide consistent spacing and layout without one-off CSS.
Fluid responsive styling (UnoCSS, container queries): A UnoCSS-driven mobile-first strategy combining clamp()-based fluid typography/spacing, media-query breakpoints for page layout, and container queries for self-contained component responsiveness.
Tables: A styled table primitive built on the primitives layer for rendering tabular data consistently across the app.
Menus (dropdown, context, menu bar): Dropdown menu, context menu, and menu bar composites built on Bits UI for triggerable and right-click action lists.
Split panes (resizable · reorderable): Resizable and reorderable split-pane primitives and composites for dividing screen space into adjustable regions.
Typography: Typography primitive components applying the design system's fluid type scale and heading/body/UI/code character rules.
Decorative (ornaments · backgrounds): Decorative primitive components (ornaments, backgrounds) used by the style-randomization system to vary visual flourish without affecting core UI predictability.

Forms & Validation

Superforms + Valibot foundation: The default form stack pairing Superforms v2 with Valibot schemas for progressive-enhancement-friendly, type-safe form validation.
Basic forms (contact · settings): Reference contact and settings forms demonstrating the standard Superforms + Valibot schema and server-action wiring for a single-step form.
Validation timing (realtime · async · server): Demonstrates the three Superforms validation timing strategies: realtime (oninput), debounced async server checks, and onblur/server-only validation.
Multi-step & dynamic (wizard · dynamic · dependent): Wizard (per-step schema validation), dynamic array fields, and dependent/cascading field patterns built on top of Superforms.
Advanced (confirm · reset · edit): Confirmation-modal submit, reset-after-submit, and edit-with-existing-data patterns layered on top of the base Superforms flow.
Auth forms (Better Auth client, not Superforms): Passwordless login (magic link + OTP) and OAuth forms built directly on the Better Auth client instead of Superforms, since Better Auth already handles rate limiting and token validation.
File uploads (withFiles + Sharp + R2): Server-side file upload handling that processes images with Sharp and persists them to Cloudflare R2, validating file metadata via Valibot rather than the file bytes themselves in-schema.
Dynamic attributes (self-describing records the user defines at runtime) deep: A record that starts almost empty and grows labelled, typed attributes its user names, with the definitions stored inline beside the values: stable attribute ids make renames free, lossy type changes keep the old value, removals are restorable, unknown kinds survive opaquely, and a fail-closed codec plus a version check guard every save, with conflicts merged by attribute id.
Form draft recovery (kept in the browser, offered back, guarded only when lost) deep: What a person types into a form is kept in localStorage per account and form, stripped of credential-like fields, offered back after a closed tab or crash (never applied on its own), cleared on a valid submit; the leave prompt fires only when the draft could not be kept.

Internationalization (i18n)

Locale routing (optional catch-all, matcher, 308 canonical): URL-based locale routing using an optional [[locale=locale]] catch-all segment and a param matcher, with the unprefixed default locale (en) 308-redirected from /en/* to keep canonical URLs.
Messages (Paraglide JS, ICU, compile-time): Compile-time translated messages via Paraglide JS v2 using ICU MessageFormat, authored as per-language JSON files that compile to typed functions.
Formatting & CLDR plural correctness: Locale-explicit date, number, currency, percent, and relative-time formatting helpers built on the native Intl API, decoupled from the translation locale to avoid SSR/CSR hydration mismatches.
DB content i18n (JSONB sidecar + `tc()`): A source-column plus JSONB-sidecar convention (e.g. name / name_i18n) for translating short database fields, resolved at read time by the tc() helper with an explicit locale argument.

Docs & Agent Experience

Docs navigation hubs (README-per-directory convention) deep: An AI-optimized docs tree where every directory's README.md is a navigation hub with topic tables, so agents read index → target file, never everything.
Pattern Index (the generated README capability map) deep: A generated table in README.md mapping every repo pattern to the doc that explains it, the code that implements it, and the showcase page that proves it — rendered from this registry (136 rows, 20 categories, two tiers).
Agent Experience (AX) surfaces deep: Five derived surfaces make the repo consumable by coding agents: a root AGENTS.md contract, raw-markdown doc variants with Accept negotiation, an /llms.txt URL map with in-band prior corrections, MCP tool errors that carry machine-actionable recovery steps, and a generated pattern library (README index + per-pattern docs pages) rendered from the pattern registry.
Resource anchor integrity (fragments and routing paths resolve): Every #fragment a registry doc ref names must be a heading the page renders, checked through the renderer's own slugger, and every path an agent instruction file routes to must exist — a narrow, build-time slice of W3C-style resource anchoring.

Data

Databases & Storage

Postgres client & connection (Neon serverless): Sets up the Drizzle client for PostgreSQL using the Neon serverless driver as the app's single database connection entrypoint.
Schema & type inference (Drizzle, 14 namespaces): Drizzle table definitions split across 14 pgSchema() namespaces and re-exported from a single schema index for compile-time type inference.
Queries/mutations split (reads-writes duality): Splits each domain's database access into separate queries.ts (reads) and mutations.ts (writes) modules.
Neo4j connection (Aura): Connects to a managed Neo4j Aura database over its HTTP Query API via fetch, with no driver, session, or connection pool.
Graph modeling: Defines how entities and their relationships are represented as nodes and edges in the Neo4j graph.
Graph traversal: Runs Cypher traversal queries, such as shortest-path and multi-hop lookups, over the modeled graph.
Polyglot freshness (Postgres ↔ Neo4j sync): Documents strategies for keeping references between Postgres and Neo4j valid, since no foreign keys exist across the two stores.
Object storage (Cloudflare R2, presigned transfer): S3-compatible object storage on Cloudflare R2, accessed via @aws-sdk/client-s3 with presigned URLs for direct client uploads and downloads.
Cache (Upstash Redis, ephemeral patterns): In-memory key-value store on Upstash Redis, reached over HTTP REST, used for rate limiting, the circuit breaker, and other ephemeral counters.
Temporal data modeling (how much time to store): A four-rung ladder — last write, transaction time (revision rows), valid time (periods, non-overlap by exclusion constraint), bitemporal — climbed only as far as a question someone actually asks; bitemporal only for auditable retroactive corrections.

Database Operations

Dev→prod schema workflow (push-only, no migrations dir): Uses drizzle-kit push for schema changes during development and defers versioned generate/migrate SQL files until production holds real data.
Neon branch refresh from prod (control plane, run ledger): Resets the dev Neon Postgres branch from its production parent through Neon's control-plane API, recording each run in a ledger and surfacing it at an admin-only page.
DB bootstrap & seed: Scripts and seed modules that populate a fresh database with baseline and sample data.

Identity & Safety

Identity & Access

Passwordless auth (magic link + OTP): Session-based authentication through Better Auth using a magic link and OTP code sent together in one email, with no passwords stored.
OAuth (GitHub, Google): Sign-in via OAuth 2.0 providers, GitHub and Google, wired through Better Auth's built-in OAuth plugin.
Route guards & per-route authorization: Server-side guard functions that check a user's capability grants or admin status before allowing access to a route or API endpoint.
Capability grants (request → approve → expire): A request-approve-expire workflow where users request a named capability, an admin approves or denies it, and pending requests auto-expire after 14 days.
Passkeys & step-up TOTP: WebAuthn passkeys serve as a phishing-resistant first-factor sign-in credential, while TOTP is repurposed as a step-up check before sensitive actions, gated by a Redis freshness stamp.
User management: User account routes and server-side data access covering profile, settings, notifications, security, and GDPR data export.

Anti-Abuse

ALTCHA proof-of-work captcha: A self-hosted proof-of-work captcha where the client solves a CPU-bound puzzle and the server verifies an HMAC-signed payload via altcha-lib.
Honeypot (hidden field + min fill time): A no-interaction bot check combining a hidden form field bots tend to fill with a minimum elapsed-time threshold between render and submit.
Rate limiting (sliding window, fail-closed): A sliding-window rate limiter factory backed by Upstash Redis that produces per-purpose limiters (email, IP, comments, grants) and fails closed when Redis is unavailable.
AI daily token budget: A per-user daily token cap stored in Redis that prevents a single authenticated user from exhausting AI quota through cost-amplification abuse.
Bot decision & abuse audit: A shared Decision type and audit trail that lets the anti-abuse layers (captcha, honeypot, rate limits) record and explain their bot/allow decisions consistently.

Admin & Privacy

Admin area, guards & data-table pattern: The overall admin area architecture — a vertical sidebar, route guards, and a canonical data-table pattern reused across admin pages.
GDPR data transparency (view · export · delete): A privacy aggregator that collects everything the app knows about a user into one report, backing the view, export, and delete surfaces required by GDPR.
Consent & cookies: Client-side consent state and a consent banner component that gate any cookie or storage write, satisfying ePrivacy/TDDDG consent requirements.
Data retention policy & purge jobs: Scheduled jobs that enforce data-retention policy by purging stale records on a fixed cadence, using the shared backend jobs framework.
Cross-device debug pairing (QR + HMAC cookie): A short-lived, single-use pairing code and QR flow that attributes a phone's anonymous pageviews to an admin's identity via an HMAC-signed cookie, without logging the phone in.
Style picking + custom palettes: A per-visitor palette, typography, and radius resolution system with a randomizer, manual picker, and optional saved custom palettes, deliberately without a site-wide brand lock.
Audit log and announcements: Admin-side systems for recording an audit trail of privileged actions and publishing site announcements, all under the admin server module.
Feedback capture: A user feedback capture form protected by the honeypot bot-detection pattern to keep submissions spam-free.
Encryption key ring (envelopes name their key, rotation re-seals) deep: Stored credentials are AES-256-GCM envelopes that name the key sealing them (a derived key id), opened by a ring of current and previous keys, so rotating ENCRYPTION_KEY is a ring change plus a re-seal sweep with a compare-and-swap on the envelope — never a mass re-entry of secrets.

Intelligence

AI

AI tool manifest & harness split (tool defs, risk metadata, registry) deep: Tool definitions are thin wrappers whose risk-tier metadata and per-surface membership live in a registry, with harness concerns (agent loop, compaction, policy) factored out separately.
AI surfaces (chatbot vs deskbot split over one guard) deep: Two AI surfaces over one shared guard: a read-only, citation-faithful chatbot (Vely) vs an agentic, mutating, approval-gated deskbot — with a showcase-only rag-demo value kept out of production paths.
Deskbot approval gate (proposal → approve, plan-gated mutation) deep: Write/destructive desk tools never mutate inside the agent loop; they return a requiresApproval sentinel that becomes a proposal (PlanCard), executed only via an approve-route replay that records the real approver and a receipt per step — and a plan that ran can be undone once, step by step, by compare-and-swap compensation.
Grounded retrieval with a corpus map deep: One shared retrieve() kernel (embed → tiers → RRF fusion) under a single user_id tenant filter, composed per turn by the chatbot profile: a deterministic corpus map anchors every turn, a relevance-gated docs lane and the catalog lane ground the prompt, and a post-stream verifier ties each path the answer names to what the turn surfaced.
Retrieval ingest/search endpoints (one ingest door, /api/retrieval/*) deep: The RAG corpus is fed and queried through /api/retrieval/* HTTP endpoints plus a unified ingest door: the app runtime and the Bun docs-ingest script share the same pure planChunks() core.
Chat assistant "Vely" (orchestrator, streaming): The chat-orchestrator module streams multi-provider LLM responses through Vely, v10r's floating chat assistant, using Vercel AI SDK v6.
Persistent minimizable chatbot session: A client-side Svelte state machine keeps Vely's conversation alive across page navigation, minimizing the panel instead of closing it when the user follows a link.
Provider registry & routing (chat/tools/vision + circuit breaker): Resolver functions pick an active chat, tool-calling, or vision LLM provider per turn and trip a Redis-backed circuit breaker on rate-limited providers.
Chatbot site awareness (page context): Server-resolved page context is injected as a passive block into the chatbot's prompt so deictic questions like "how does this work?" resolve to the page the user is viewing.
Graph RAG pipeline (three tiers, RRF fusion): Vector-similarity chunk retrieval is combined with Neo4j knowledge-graph traversal across three parallel tiers, fused by reciprocal rank fusion, for more explainable answers.
Turn trace (recorded account of every AI turn) + turn graph: Every chatbot and deskbot turn records what was available, considered, included per model call, executed and cited — from the actual execution, never a second run — streams it while the turn runs, persists it once, and lets the turn’s owner open it as a three-column turn graph (sources → context and model calls → tools, recorded relations only), a tree and a timeline on the showcase pages.
Image metadata reader (vision): A vision-capable LLM proposes title, caption, alt text, keywords, and category for an uploaded image, which a human reviews and approves before anything persists.
Cost & usage monitoring: Chat and image telemetry are merged into one admin table that derives a reference token cost at read time from a hand-maintained price table, without charging or faking a real bill.
TOON token-efficient context format: A compact, TOON-style serialization packs structured context data for LLM prompts more densely than JSON, currently implemented as a hand-rolled layout rather than the external @toon-format/toon library.
Deskbot (AI in the desk workspace): An agentic AI surface embedded in the desk workspace calls desk-mutating tools, with writes routed through the harness's proposal-and-approval gate.
Agent-harness audit lens (loop/context/policy/tools): A conceptual audit lens (not a module) names which slice — loop, context, policy, or tools — owns each agent-harness primitive such as compaction, step caps, and approval gating.
Untrusted-content boundary (the lethal trifecta, one rule per leg) deep: Every AI tool declares where its result comes from and whether it can send data out; user-origin results reach the model as one escaped <untrusted-content> element (this turn via toModelOutput, replayed turns via the history), external-reach tools must be approval-gated, and model output renders no image or unlisted link — a gate test holds all three legs.
AI eval regression suite (golden set, deterministic graders over the turn trace, floor ratchet) deep: A committed golden set of questions, each with the facts its recorded turn must show — citations surfaced not recalled, the right tool called, no forbidden tool, an approval stop, no invented command — graded by pure functions over the turn trace, with a pass-rate floor that only rises; live runs go through the app's own routes against a local dev server.

Toolkits

Image Kit (upload → AI pipeline → adjust → approve, persists nothing): A single-page toolkit that chains an AI metadata reader, frame-cropper, and embedder on one uploaded image, then discards the upload after an honest approval terminal.

Office Workflows

PIM Excel workflow with AI agents (profile, proposed recipe, deterministic run, target check) deep: Supplier Excel/CSV product exports become a target's import sheet without the model touching a row: the agent reads a bounded column profile and proposes a typed transform recipe, a column walk refuses imagined columns, code runs the recipe over every row (unreadable values left unchanged and listed by source line), and a target-schema check over the full output is the definition of done — in a bounded propose → run → check → revise loop, in-app, or from a terminal agent with the `pim` program over plain job folders (no git, no repo; one dated output folder per run).

Features

Analytics

Pageview collector hook (last of 14 middleware stages): A hooks.server.ts middleware stage that runs last in the 14-stage sequence and records public GET pageviews into separate anonymous and authenticated lanes only after auth and routing have resolved; sessions gain human_confirmed_at via a consent-free confirm ping so dashboards count JS-corroborated visitors, and collection is muted in dev because every environment shares one database.
Consent-gated sessions (cookieless day-rotating id): Session identification switches between a cookie-based id under the analytics consent tier and a cookieless hash(visitorId + UTC day) id under the necessary tier, so both tiers still produce a countable session.
User journeys (client beacon): Page-to-page journeys are computed in Postgres with a LEAD() window function over consecutive pageviews in a session and shown as a ranked table rather than an aggregate flow diagram.
Funnels: Funnel conversion is computed as count(distinct session_id) per step in one grouped query, so a reload mid-funnel is deduped instead of double-counted.
Live events feed: An unauthenticated, self-limiting SSE stream at /api/analytics/stream pushes live event-style updates for the showcase demo, using synthetic rather than production data.
Rollup & cleanup jobs: Two scheduled jobs aggregate yesterday's events into a daily_page_stats table and enforce per-table retention windows (60-180 days) across the analytics tables.
Visitor "my data" transparency: An authenticated "Your data" page streams cookie state, live request metadata, and a full collectUserData report so a visitor can see what analytics has captured about them.

Notifications

Router, outbox & delivery worker: sendNotification() writes an in-app record, evaluates the settings matrix per channel, then queues outbox rows delivered by an in-process worker on containers or a cron sweep on Vercel.
Channel providers (email · Telegram · Discord): Email (Resend), Telegram (bot API), and Discord (OAuth2) each implement a common provider interface (send/validateConnection/getProviderName) behind their own connection and token-management flow.
In-app SSE stream & notification center: One SSE route serves notifications in real time over two transports: an in-memory connection map on a persistent host, Redis pub/sub on Vercel serverless; the account pages re-run their load via invalidate() instead of holding a stream open.
Settings matrix (channel × type): The settings UI renders a channel-by-notification-type matrix backed by a form schema, letting a user toggle which channels receive which notification types.
Schema & delivery log: The multi-channel schema adds per-user channel-connection tables, verification tokens, and push subscriptions, plus a notification_deliveries table logging per-channel send status.

Jobs & Scheduling

Jobs & scheduling (registry, runner, platform-owned cadence) deep: A slug → {execute, cadence} job registry with a unified runner. The registry owns what runs and how often it is due (daily | weekly); the platform owns only the clock — one daily /api/cron/due sweep on Vercel, a flat interval on persistent hosts — so switching hosts needs zero job-code change.
Platform scheduling (Vercel cron vs container `setInterval`): Cadence is owned entirely by platform config — vercel.json crons hitting /api/cron/[job] on serverless, or a single flat setInterval scheduler on persistent containers — so the job registry itself never changes when switching hosts.
Registered jobs (retention, cleanup, sync, delivery): The concrete job implementations — retention sweeps, cleanup, external sync, and delivery — are idempotent slug-keyed functions run by the shared runner and manageable from an admin UI.

PWA

Localized manifest & installability: The web manifest is served dynamically so name/description follow the Paraglide locale cookie, with maskable icons and an explicit cache header that pre-empts the hooks' no-store stamp.
Service-worker caching contract (HTML network-only, kill switch): The custom service worker precaches only the icons and the offline page's own assets (parsed from its HTML), fills the rest of the hashed build cache-first as it is used, serves HTML and __data.json network-only, never intercepts /api/* or SSE, and ships a kill switch that force-wipes caches and unregisters on a bad deploy.
Update flow (silent + idle toast, no auto skipWaiting): A pending service-worker update rides the next client-side navigation silently, or for navigation-less sessions surfaces one persistent reload toast after 30 minutes, and never auto-activates with skipWaiting().
Web push channel (declarative JSON, no PII): Web push uses one Declarative Web Push JSON payload carrying no PII (brand title, generic body, same-origin navigate path) so real content only loads after tap-through session auth, delivered synchronously and bypassing the outbox.

Data Viz

Charts: Chart.js wrapper components for standard statistical charts (bar, line, area, pie, radar, bubble, scatter) with SSR-safe canvas lifecycle handling.
Plots: Chart.js scatter plots and a canvas-based heatmap component for visualizing continuous or correlated data.
Diagrams: @xyflow/svelte-based flow and state diagram components with custom node types for interactive node-edge visualizations.
Node graphs: D3-powered network, tree, DAG, Sankey, and knowledge-graph layout components, rendered as SVG by Svelte while D3 only computes positions.
Maps: MapLibre GL components for a base map, markers, and GeoJSON choropleth overlays, using free CartoDB tiles.
Timelines: Timeline visualization components for displaying a sequence of dated events.

3D

Threlte integration (SSR-off, code-split model registry): Threlte 8 is wired into SvelteKit with SSR and prerendering disabled for the 3D route subtree, plus a static model config registry driving camera, lights, and controls.
Static & animated scenes: A shared scene component that renders either a static GLTF model with orbit controls or one with animation clips playing via an AnimationMixer.
Full-screen model viewer & customizer (layout reset): A full-screen model viewer and GLTF customizer (materials, parts, morph targets, presets) that resets the app layout while open.
Product composition engine (typed ports, couplings, conduits) deep: Reusable 3D products with typed connection ports join into an editable assembly: a framework-free core keeps definitions, occurrences, ports, couplings, conduit routes and port rules apart, validates and edits them deterministically, and a thin Threlte layer renders and edits the result.
Asset production pipeline (typed request → checked GLB) deep: A structured, validated request becomes a checked 3D asset: a deterministic TypeScript generator builds parametric geometry, an inspector proves every shell closed and outward, a DOM-free writer emits byte-stable GLB with its derivation key inside and reads it back, and one job shape — report, PROV-DM provenance, measurements, a write-once owner-scoped store — serves an HTTP route, a CLI and MCP tools, in-process or in a killable worker process.

Content & Blog

Blog engine (posts, revisions, locale-aware publishing): A DB-backed blog system with posts, immutable revisions, and locale-aware publishing supporting multiple authors.
Comments (flat, per-locale, moderated): A flat, per-locale comment system with a short author edit window and admin moderation (hide/unhide/remove).
Markdown pipeline & custom syntax (directives, wikilinks): A remark/rehype-based markdown rendering pipeline extended with custom directive syntax for embeds; wikilink cross-references are designed for but not yet implemented.
Markdown editor (CodeMirror, slash commands): A CodeMirror-based source markdown editor with a slash-command palette that auto-inserts custom syntax.
Prerendered docs site: A prerendered documentation site where each page both explains and demonstrates the feature it documents.

Desk Workspace

Desk workspace (dock layout, focus architecture, mobile projection) deep: A full-page multi-panel workspace on a binary split-tree dock: resizable panes, drag-and-drop tabs, a panel-type registry, typed cross-panel pub/sub (DeskBus), one persisted desktop tree with total focus derivation, and a mobile chrome that is a projection over the same state — never a second layout.
Spreadsheet panel (file type, dual-mode): A spreadsheet file type managed through the desk's unified file registry, editable in a dual-mode (grid/panel) UI, with one formula evaluator shared by the grid and the AI write path so a stored sheet never disagrees with itself.
Desk mobile chrome (tab strip + pill + drawers): Phone chrome for the dock workspace: a scrollable top tab strip of open panel instances, a bottom-right controls pill (commands sheet + panels drawer) sitting left of the app FAB via slot tokens, and a soft-keyboard watcher that hides floating chrome while typing.
Composed panel menus (one array, desktop kebab + mobile sheet): A context-scoped registry where each panel instance registers its command menus, composed with a dock-supplied Panel floor menu and View menu into one array that the desktop kebab and the mobile commands sheet both render.
AI desk effects (tool results drive the workspace): AI tool results dispatch typed desk effects (open/focus/refresh/highlight/notify/scroll) through an EffectActions facade; the dispatcher returns applied/failed per effect and failures surface in the I/O Log panel instead of being swallowed.
Explorer panel (unified file tree over N sources): One recursive tree over heterogeneous content APIs: adapters normalize every source into an ExplorerNode with a capability set, and the context menu, touch kebab, drag-and-drop, and inline rename/delete are all driven by capabilities — not per-type branching.

External Integrations

Name check (resilient multi-source fan-out) deep: One report from several unreliable upstreams: concurrent per-source deadlines, a breaker, bulkhead and daily quota per source, per-source coverage instead of failure, dependency-free name similarity, and a descriptive conflict signal that never claims legal availability.

Velocity

Interaction Velocity

Optimistic mutation (fold-based rollback, idempotency keys) deep: The confirmed value and the pending intents are stored separately and the UI reads the fold of one over the other, so a failed mutation rolls back exactly — even with later mutations applied on top — and a repeated intent executes once.
Intent-based preloading (six levels over SvelteKit triggers) deep: A policy layer over the app-wide `data-sveltekit-preload-data="hover"` default, for the two cases the blanket setting gets wrong: routes too expensive to speculate on, and next screens predictable enough that waiting for a hover wastes the idle time.
Virtualized rendering (windowing maths split from the component) deep: A long list costs the size of the viewport instead of the size of the data; the windowing arithmetic lives in a pure module so its edge cases are testable without a browser, while the component owns only the effects.
Idle and speculative work: Useful non-critical preparation performed after the page is interactive: preloading probable code, hydrating embeds on intersection, and the PWA's idle update toast, which never calls skipWaiting on its own.

Data Velocity

Hierarchical cache (local → shared → origin, with key scope enforced) deep: A read walks outward from process memory to Redis to the origin. The policy declares namespace, TTL, stale window and scope, and `cacheKey` refuses both scope mistakes — a per-user key with no owner, and a shared key handed one.
Stale-while-revalidate (and stale-if-error) deep: A value past its TTL but inside its stale window is returned immediately and refreshed behind the response; a failing refresh leaves the stale value in place rather than turning a slow dependency into a 500.
Singleflight / stampede protection (nobody waits on a lock) deep: Concurrent callers for one key share one execution, and across instances a refresh claim stops N instances refreshing the same stale key N times — but a cold caller never blocks on a lock, so a failed leader can never become an outage.
No-waterfall data loading deep: Independent operations execute concurrently; sequential waiting requires a real dependency. The same round trips happen either way — only the waiting is removed, which is why the fix is free.
Screen read model: Frequently-read views are served from a purpose-built projection instead of rebuilding the same joins per request — analytics rollups, the Neo4j catalog projection, and the per-locale prerendered search shards.
Query budget and N+1 proof (counting is not proving) deep: Database round trips counted per request by the driver's own logger, and per operation by a gate that runs each one over two data sizes — because N+1 is a claim about how cost SCALES, which no single request can settle.

Runtime Velocity

Critical path / deferred tail deep: Only work the caller's intent depends on runs before the response; analytics, indexing, outbox routing and telemetry run after it through one wrapper that owns the platform's survival rule and the catch-before-handoff rule.
Critical rendering path (the LCP element paints from the document) deep: What the first viewport needs paints from the server HTML and its render-blocking CSS: no hydration gate on visible content, and a late-discovered LCP graphic inlined server-side once, with a hashed CSS-mask fallback for client navigation.
Heavy dependency quarantine (the baseline is the metric) deep: Optional heavyweight capabilities load behind dynamic-import boundaries, and the gated metric is not the route's own size but the shared baseline every other route pays — `baseline_js_kb`, ratcheted with ~3% headroom.
Side-effect-free component tree (barrels that tree-shake) deep: Compiled Svelte components run code at module scope, so the bundler keeps every component a barrel re-exports. Declaring the component directory side-effect free in the bundler makes an unused export droppable — and an import made for side effects alone silently vanishes, which a gate forbids.
Main-thread budget (worker → WASM, each step measured) deep: Expensive browser work moves off the main thread only where measurement justifies it: cheap stays inline, noticeable CPU work goes to a Web Worker, and WASM is reached for last — benchmarked against a line-for-line JS implementation including transfer cost.
Resilience policy (breaker, bulkhead, shedding, bounded retry) deep: Four separate decisions about an unhealthy dependency — should we call it, how much of the pool may it hold, is this work worth doing under pressure, and is this failure worth repeating — kept apart because none of them substitutes for another.
Asset delivery pipeline deep: Keeping images and fonts from dominating page load: metric-matched fallback faces generated from the font files, fonts deliberately not preloaded, and an R2 image redirect the CDN can actually cache (s-maxage, URL stable per presign window).
Compute and data locality: A locality map derived from the environment rather than typed into a table: which region each system runs in, which of them are not observable at all, and the cross-region hops one request actually pays.
Deadline propagation (one budget, divided) deep: A latency budget stamped once at the edge, from which every downstream operation takes what is LEFT rather than a fresh window of its own — so the request has a stated bound instead of the sum of independently-chosen timeouts.

Velocity Measurement

Latency tracing (a v10r span API, Server-Timing as one renderer) deep: Every layer records spans into a request-scoped recorder stamped by the outermost handler; `Server-Timing` renders them for callers who already see internals, and `unattributed` reports the wall-clock time no span claimed.
Performance budget and ratchet (targets aspire, ceilings hold) deep: Two thresholds with different jobs: targets are where we want to be and never fail a build, ceilings are the measured value at the moment it was accepted and only ever move down. A gate wired to a target gets muted the afternoon it is added.
Performance scenario harness (adverse conditions, committed) deep: Representative paths driven under one adverse condition at a time — cold cache, expiry burst, hanging dependency, failing dependency, concurrency, refusal — with the deterministic columns gated and the timings only reported. A system is not proven fast because localhost is fast.

Integrity

Truth & Evidence

Source-of-truth gate (one owner, bound copies) deep: Every fact has exactly one owner; every other copy is typed, imported, generated with a --check, or bound by a drift test with a non-empty control — and reading the owner fails closed instead of falling back to a second source.
Evidence status dimensions (verdict, coverage, confidence, freshness kept apart) deep: "How sure are we?" is several questions — what the evidence suggests, how far we looked, who produced it and how confident they were, whether the reference still resolves, and when it goes stale — each stored in its own field, never merged into one score.
Asset rights manifest (owned rights record + gate over shipped files) deep: Every third-party file the app ships carries one AssetRights record (author, SPDX license, source) owned by the module that uses it, derived into every surface that credits it, and gated against the files actually present — metadata presence and shape, never a legal conclusion.

Derivation & Provenance

Derivation key (freshness by input fingerprint) deep: A derived output stores derivationKey(transform@version, inputs) beside itself and is current exactly while a recomputed key matches — catching the code changes a content hash cannot see, and skipping re-derivation when nothing moved.
Reproducible artifact build (regenerate-and-diff, or manifest + digest) deep: Committed generated artifacts are proven current by the gate: regenerate-and-diff (missing and orphan outputs included) when the generator can run there, an SLSA-shaped manifest of input/output digests plus a pinned toolchain when it cannot — each artifact labelled bit-for-bit or input-addressed.
Provenance record (entity, activity, agent — PROV-DM core) deep: Where a value came from is recorded with the W3C PROV-DM core only: the entity pinned to a revision or content hash, the activity with its transform version, and the agent (human, software or AI, on whose behalf) — with an explicit erasure decision per trail.

Durable Execution

Durable step execution (claim, lease, fence, receipts) deep: Multi-step work that can be killed halfway survives without a workflow engine: a conditional status machine, one claim, a database-clock lease with a reaper, a fence so a stale owner cannot write, and per-step receipts committed with each step's effect.
Versioned document session (save queue, drafts, CAS, explicit conflict) deep: A browser-edited document stays server-authoritative: debounced serialised saves carrying their base version, compare-and-swap rejection as an explicit conflict state, per-writer local drafts no other tab can erase, and reloads that fetch before they replace.

← Back to Docs

Думаете, этот паттерн можно сделать лучше? Расскажите как.

Оставить отзыв