System Abstraction

The v10r system is organized as a seven-layer abstraction hierarchy where each layer is built from the one above it. Data flows down from HTTP edge to infrastructure; events and responses bubble back up. This document is the entry-point map for understanding how the whole system fits together — read it before diving into any single layer.

Two physical spines hold all seven layers together: a composition root (src/hooks.server.ts) that owns cross-cutting concerns, and a hexagonal core (src/lib/server/[domain]/) where all business logic lives, insulated from the framework.

The Hierarchy at a Glance

Layer                    Canonical Home
─────────────────────────────────────────────────────────────────────────────
1  Tech Stack            root config (svelte.config.js, vite.config.ts,
                         uno.config.ts, drizzle.config.ts, package.json)
                         + Containerfile.dev / compose.yaml

2  Architecture          src/hooks.server.ts  (composition root)
                         + multi-client-core pattern
                         server/client boundary = the $lib/server/ path

3  Services/Applications src/routes/[[locale=locale]]/  (app/, admin/, desk/,
                         auth/, (public)/showcases/)
                         + parallel src/routes/api/ tree

4  Modules               src/lib/server/[domain]/
                         + src/lib/[client-domain]/
                         public surface = each module's index.ts barrel

5  Components            src/lib/components/[layer]/
                         primitives → composites → layout/shell → feature dirs

6  Classes/Functions     files inside a module/component folder;
                         private unless re-exported from folder's index.ts

7  Code                  leaf .ts / .svelte / .css;
                         design tokens at src/lib/styles/tokens.ts + src/app.css
─────────────────────────────────────────────────────────────────────────────

The seven layers collapse into two physical spines:

• Composition root — src/hooks.server.ts wires together Layers 1–3: it boots background modules, runs a 14-stage sequence() of Handle middleware, and hands a fully populated event.locals to every route adapter.
• Hexagonal core — src/lib/server/[domain]/ houses Layers 4–6: framework-free domain modules that any adapter (UI, REST, AI tool, job) can call without modification.

Layer 1 — Tech Stack

The foundation is declared in root config files and Containerfile.dev; nothing above Layer 1 should care which specific vendors implement it.

Runtime environment

Data stores (polyglot persistence)

Application concerns

Design principles (docs/foundation/principles.md): libraries-over-services, lightweight, standard protocols, free-tier-friendly, svelte-native-first, no-codegen, speed-is-a-feature. The no-codegen constraint is consequential: Better Auth schema is hand-written Drizzle tables rather than auto-generated.

Connects down to Layer 2 by providing the runtime these patterns run in. No Layer 2 code imports the vendor names directly; it imports from wrappers in $lib/server/[domain]/.

Layer 2 — Architecture

Two architectural spines impose order on every request.

Spine A — Composition Root

src/hooks.server.ts is the composition root. Three module-load side effects at the top of the file boot background work once at process start:

import '$lib/server/agents'
import '$lib/server/jobs/scheduler'
import '$lib/server/jobs/delivery-scheduler'

The main export is a sequence() of fourteen Handle middlewares that mutate the shared event.locals bus in order. Each handler writes named fields and, in some cases, short-circuits the chain with a response before downstream handlers run.

The terminating error handler handleError mints an errorId (crypto.randomUUID()), emits one structured JSON log line, and returns { message, errorId } to the client — never raw error details.

Security Headers set

securityHeaders (handler #1) writes these on every response (wrapped in try/catch — redirect responses have immutable headers):

CSP itself is configured in svelte.config.js (nonce/hash mode), not here.

Extracted handler helpers

Several handler predicates were lifted into framework-free modules the hook imports — behavior unchanged, now unit-testable in isolation:

Spine B — Hexagonal Multi-Client Core

All business logic lives in $lib/server/[domain]/. Thin adapters wrap it for each client type. The domain modules know nothing about the framework.

┌──────────────────────────────────────────────────────────────┐
│                          ADAPTERS                            │
│                                                              │
│  +page.server.ts   +server.ts   AI tools       jobs/         │
│  (form actions,    (REST API,   (tool           (cron,       │
│   load fns)         SSE)        wrappers)        sched.)      │
└──────┬───────────────┬───────────┬──────────────┬───────────┘
       │               │           │              │
       ▼               ▼           ▼              ▼
┌──────────────────────────────────────────────────────────────┐
│                      DOMAIN MODULES                          │
│                 $lib/server/[domain]/                         │
│                                                              │
│  notifications/    auth/         rawrag/      llmwiki/        │
│  ├── index.ts      ├── index.ts  ├── index.ts ├── search.ts  │
│  ├── service.ts    └── guards.ts └── ...      └── ...        │
│  └── ...                                                     │
│                                                              │
│  db/[domain]/                                                │
│  ├── queries.ts   (reads — no side effects)                  │
│  └── mutations.ts (writes — explicit intent)                 │
└──────────────────────────┬───────────────┬───────────────────┘
                           │               │
                           ▼               ▼
┌──────────────────────┐  ┌────────────────────────────────────┐
│  PostgreSQL           │  │  Neo4j  │  Redis  │  R2            │
│  (Drizzle ORM)       │  │  (graph)│ (cache) │  (storage)     │
└──────────────────────┘  └────────────────────────────────────┘

The four invariants — violations break cross-client reuse:

1. No framework imports in domain modules. No @sveltejs/kit or $app/ imports inside $lib/server/[domain]/. These bind logic to the SvelteKit request cycle, preventing reuse by AI tools and jobs.
2. Date serialization happens in the adapter layer. Domain modules return Date objects as-is. The route or tool execute converts them to ISO strings.
3. SvelteKit response helpers (redirect, error, fail, message) only in adapters. Never in domain modules.
4. Domains call down, not across. Cross-domain reads go through the other domain's index.ts barrel only — never into its internals.

Server/client boundary: the $lib/server/ path itself. SvelteKit refuses to bundle it client-side. No runtime guard is needed; the path is the boundary.

Error spine: ServerError base class (src/lib/server/errors/index.ts) with kind / toStatus() / toJSON(). Subclasses: DbError (maps PG SQLSTATE → safe message + HTTP status), AIError, Neo4jError, LlmwikiError. Each adapter translates: REST endpoints return apiError(status, kind, safeMessage); AI stream tools return structured error objects (never throw); form actions use fail(); jobs capture into JobResult. Safe messages only — no PG codes, constraint names, or API-key prefixes reach the client.

Layer 3 — Services / Applications

Route areas under src/routes/[[locale=locale]]/ and the parallel src/routes/api/ tree define the bounded contexts. Each context owns a route area, an API group, and primary server domains.

Self-documenting showcases: pages under (public)/showcases/ serve simultaneously as documentation, feature tests, and copy templates. If the showcase works, the feature is proven. This is the repo's primary test strategy for UI patterns.

Layer 4 — Modules

src/lib/server/[domain]/ holds ~40 server-side domain modules. src/lib/[client-domain]/ holds client-side state, styles, i18n, schemas, and config. The public surface of every module is its index.ts barrel export — external callers import from the barrel only, never from internal files.

Server-side domains (selected by file count)

Repeating module template

[domain]/
  index.ts           ← barrel / public API
  service.ts         ← multi-step orchestration (only when justified by ≥2 concrete consumers)
  queries.ts         ← reads; no side effects
  mutations.ts       ← writes; explicit intent
  types.ts
  config.ts
  errors.ts
  [feature].ts       ← one file per capability
  *.test.ts          ← co-located unit tests
  [sub-pipeline]/    ← e.g. rawrag/tiers/, rawrag/ingest/, ai/tools/, ai/loop/

Deviations: auth/index.ts is the Better Auth instance (construction site, not re-export). ai/index.ts exposes provider-resolver functions. Tiny modules (utils/, errors/, schemas/, feedback/) skip the full structure.

The db/ module — parallel-tree structure

db/ is the most structurally important domain. It contains two co-located trees:

src/lib/server/db/
  index.ts                  ← Drizzle client over Neon serverless Pool
  errors.ts                 ← DbError, classifyDbError
  schema/
    [domain]/               ← what data IS (Drizzle table definitions)
    index.ts                ← re-exports every domain schema
    relations.ts            ← Drizzle relation definitions
  [domain]/
    queries.ts              ← how you read data
    mutations.ts            ← how you write data

db/index.ts exports the singleton db instance:

neonConfig.poolQueryViaFetch = true; // Bun WebSocket workaround
const pool = new Pool({ connectionString: env.NEON_DATABASE_URL_PROD });
export const db = drizzle(pool, { schema: { ...schema, ...relations } });

Push-only workflow: only db:push is used; no migrations directory exists. All pgSchema() and pgEnum() objects must be exported through schema/index.ts AND listed in drizzle.config.ts schemaFilter (14 namespaces: admin, showcase, image, auth, ai, rag, jobs, notifications, analytics, app, blog, dbops, desk, feedback) or db:push silently omits them.

Client-side modules

Import direction

The import graph is a verified DAG. Cross-domain references always target barrel roots — never internals. The db/ module imports no sibling domains; it is the sink. Framework coupling is confined to adapter-purpose files (auth/guards.ts, api/response.ts, api/rate-limit.ts, abuse/decision.ts) and scheduler-boot code that reads the building / dev flags. Pure domain modules — db/, rawrag/, blog/, store/, llmwiki/, ai/providers — have zero framework imports.

Layer 5 — Components

src/lib/components/[layer]/ organizes 22 categories in a dependency-direction hierarchy.

Layer order (leaf → root)

primitives/     wrap Bits UI: button, dialog, table, slider, combobox,
                tabs, typography, switch, popover, calendar, …

composites/     compose primitives: card, form-field, command-palette,
                dropdown-menu, pagination, toast, confirm-dialog, dock,
                chatbot, page-header, empty-state, …

layout/         Stack, Cluster, PageContainer

shell/          app chrome: AppShell, Sidebar*, Nav*, UserMenu,
                ConsentBanner — depend on composites/primitives/layout

feature dirs/   blog, chat, editor, explorer, spreadsheet, viz, cycle,
                io-log, branding, 3d, docs, ui, preview, admin —
                depend DOWNWARD on composites/primitives/layout; never
                on each other

Public barrel (src/lib/components/index.ts)

export * from './composites';
export * from './layout';
export * from './primitives';

// viz/ excluded — import from '$lib/components/viz' directly
//   (avoids bundling Chart.js/Three.js into the default surface)
// shell/ excluded — app-specific chrome, import from '$lib/components/shell'

viz/ and shell/ are intentionally excluded from the default barrel. This is a bundle-size boundary: Chart.js, Three.js, and app-specific chrome should not load on every page.

Design tokens

• src/app.css — runtime CSS custom properties (:root light, .dark dark). All color tokens live here.
• src/lib/styles/tokens.ts — build-time token values (breakpoints, fontSize, spacing, borderRadius, zIndex, iconSize) read by uno.config.ts.

Component-First Rule: never use a raw HTML element (<button>, <input>, <select>, <textarea>) when a project component exists. Raw elements bypass the design system. Exceptions: <input type="hidden">, <input type="checkbox"> in table rows for native indeterminate support, <select> binding numeric values, and custom interactive regions needing specialized styling.

Layer 6 — Classes / Functions

Individual files inside a module or component folder. Private by default; public only when re-exported from the folder's index.ts.

Recurring kinds

Guards (auth/guards.ts):

Step-up gate (auth/step-up.ts): requireStepUp / isStepUpFresh / stampStepUp over a Redis stepup:<userId> key (600s). Reads Redis, never the session (freshness must not ride the cookie cache); fail-closed in prod. Never imports the auth instance — auth/index.ts imports from it via its hooks. factor-changes.ts:onFactorChanged is the single chokepoint for passkey/TOTP side effects (audit + sibling-revoke + email). See blueprint/auth.md.

Services — multi-step orchestration warranting extraction: NotificationService.send() (DB insert → SSE push → async channel routing).

Domain functions — the shared call site for all adapters: getNotifications, markAsRead, retrieve (rawrag), searchLlmwiki, getCustomPaletteById.

Read/write seam: queries.ts contains reads with no side effects; mutations.ts contains writes with explicit intent. This split is a naming convention, not a CQRS infrastructure.

Error classes and classifiers: ServerError → DbError / AIError / Neo4jError / LlmwikiError; classifyDbError / classifyAIError / classifyNeo4jError; safeDbMessage / safeAIMessage.

Provider resolution (ai/providers.ts): getActiveProvider / getToolProvider resolves in order: request override → user preference → env → first configured. Circuit breaker: markCooldown / isCooledDown (60-second window), Redis-backed (ai:cooldown:{id}) so it is cross-instance and async.

AI tools (ai/tools/): desk-read, desk-write, propose-plan, get-rawrag-chunks, get-llmwiki-pages, resolve-ref, search-catalog, search-docs. All are thin wrappers that return structured data and never throw — tools return error objects; the LLM reads them.

Catalog grounding (ai/catalog-citations.ts, ai/tool-leak-guard.ts): post-stream surface-citation verifier and Groq/llama textual-tool-call leak guard. See blueprint/ai/provider-routing.md.

Catalog graph (search/catalog-map.ts, search/catalog-projection.ts, graph/catalog.ts): formatCatalogMap injects a path-free shape hint into the system prompt; deriveCatalogGraph projects the showcase registry to typed :Resource nodes + PART_OF edges; seedCatalogResources writes them to Neo4j idempotently (run via db:catalog-sync, chained into db:setup).

Docs corpus (rawrag/markdown-split.ts, ai/tools/search-docs.ts, scripts/db/ingest-docs.ts): the project's own docs/**/*.md is ingested into rag.document/rag.chunk (owned by SYSTEM_DOCS_USER_ID) so the search_project_docs tool can ground "how does X work" answers in the real docs. Ingestion is manual — db:ingest-docs (not chained into db:setup). See blueprint/ai/layered-rag.md.

CVA variant definitions (e.g. button.ts): class-variance-authority variants double as DOM markers for scoped CSS selectors (UnoCSS cannot extract complex classes from .ts files reliably; Button.svelte scoped CSS does the actual styling, targeting CVA class names as :global() selectors).

Layer 7 — Code

Leaf .ts, .svelte, and .css files. The execution substrate.

Languages and type discipline: TypeScript strict mode throughout. Svelte 5 runes ($state, $derived, $effect, $props) for all reactive state — no Svelte 4 stores. CSS custom properties for all theming.

Recurring idioms:

Data Flow & Wiring (Runtime)

Descent diagram

HTTP edge
  │
  ▼
hooks.server.ts  sequence()  ──────────────────────────────────────────┐
  │  (14 stages, mutate event.locals)                                  │
  │  [securityHeaders → bodySizeFloor → stripBaseLocalePrefix →        │
  │   docsMarkdown → loadStyle → i18n → authCaptchaGate →              │
  │   authHandler → csrfProtection → sessionPopulate →                 │
  │   consentLoader → debugOwnerLoader → devRouteGuard →               │
  │   analyticsCollector]                                              │
  │                                                                    │
  ▼                                                                    │
Route adapter  (event.locals fully populated)                          │
  │  +page.server.ts  |  +server.ts  |  ai/tools/  |  jobs/           │
  │                                                                    │
  ▼                                                                    │
Domain module  $lib/server/[domain]/  (no framework imports)           │
  │  Pure TypeScript; calls db/, calls infra via injected clients      │
  │                                                                    │
  ▼                                                                    │
db/[domain]/{queries,mutations}.ts                                     │
  │                                                                    │
  ▼                                                                    │
Infra boundary ───────────────────────────────────────────────────────┘
  Postgres/Neon · Neo4j/Aura · Upstash Redis · R2 · AI providers · channels

Data flows down. Responses bubble up the same chain. The event.locals bus is the handoff between the middleware column and the route-adapter column.

Infra boundary crossings

Multi-client adapter table

Authentication per client: session cookie for UI and REST (populated by sessionPopulate in hooks); closure capture of userId for AI tools (auth happens once at the chat endpoint, user.id flows into createTools(user.id)); none for background jobs (trusted server context).

Traced flows (wiring inventory)

Nine end-to-end flows have been traced through the system:

1. Request lifecycle — HTTP edge → hooks pipeline → route adapter → domain → DB → response
2. Multi-client core (notifications) — same getNotifications / markAsRead called from UI, REST, AI tool, and job
3. AI chat + tool-calling — orchestrateChat in ai/chat-orchestrator.ts; provider resolution → streamText → tool loop → persistence
4. RAG retrieval — retrieve in rawrag/index.ts fans out across tiers/ (tier-1 searchContextual = pgvector + BM25 fused via reciprocal-rank fusion, tier-2 searchParentChild, tier-3 searchGraph — Postgres seeds → Neo4j expand → Postgres hydrate)
5. Notification delivery — NotificationService.send() → DB insert + SSE push + web push (both synchronous) + channel routing (async via outbox: Telegram / Discord / email). The outbox drain is a claim-based queue worker: rows are taken with an atomic FOR UPDATE SKIP LOCKED claim, terminal writes are fenced on attempts, and a lapsed lease is reclaimed inside the same drain. See blueprint/architecture/workers.md
6. Background jobs — runJob() + scheduler (setInterval, persistent container) vs cron dispatcher (/api/cron/[job], serverless); same runner, different trigger
7. Visual identity — loadStyle in hooks resolves cookie → custom palette DB lookup (CP_ ids only) → generateRandomStyle fallback; Paraglide transformPageChunk injects palette CSS into every HTML response. There is no site-wide brand override: every visitor's style is their own
8. Auth + session + grants + analytics — authHandler (Better Auth) → sessionPopulate (locals.user/session/grants) → analyticsCollector (consent-tiered, fire-and-forget). Factor mutations (passkey/TOTP) route through two global Better Auth hooks in auth/index.ts: a before step-up gate and an after chokepoint that audits, revokes sibling sessions, emails, and stamps step-up freshness. Passkeys are a phishing-resistant first factor; TOTP is a step-up factor only (passwordless sign-ins are never challenged). See blueprint/auth.md
9. Personal-data access (privacy) — collectUserData in privacy/report.ts is the one aggregator behind four adapters: the /account/data page load (streamed), GET /api/me/data, GET /api/me/data/export, and DELETE /api/me (via deleteUserData). One definition of "all my data"; secrets projected out at the query, prior-session IPs masked. Erasure is the Postgres FK cascade plus a best-effort deleteUserGraph sweep (Neo4j has no FKs). See stack/capabilities/gdpr.md

Drift from Blueprint & Known Gaps

These gaps make the blueprint-to-code mapping imperfect. They are recorded here, not concealed, so the doc remains trustworthy.

1. No notification AI tool implemented. multi-client-core.md uses createNotificationTools / markNotificationRead as its flagship example. ai/tools/ currently holds desk, llmwiki, rawrag, propose-plan, and resolve-ref tools. Multi-client reuse for notifications is real for UI, REST, and jobs — not yet for AI.

2. Daily token budget is enforced. chargeTokens records daily AI spend to Redis in onFinish; the entry-gate checkUserBudget (ai/budget.ts) now runs in the shared guardAiRequest (ai/guard.ts) before orchestrateChat, rejecting once the day's spend exceeds the cap. (It was previously called nowhere — recorded but unenforced.)

3. notification-delivery drains on every platform. It is registered in the jobs registry (jobs/index.ts) and scheduled in vercel.json (/api/cron/notification-delivery, daily — Vercel Hobby rejects sub-daily crons at deploy time) — on Vercel the cron sweep is what drains pending Telegram / Discord / email deliveries. On persistent platforms the 15-second delivery-scheduler setInterval still owns it; the cron never fires there. Web push bypasses the outbox entirely — it is partitioned out before createDeliveries runs and sent synchronously inside NotificationService.send(), alongside in-app SSE. (It previously had no serverless trigger and was absent from the registry, so deliveries queued as pending and never drained on Vercel.)

4. Per-surface chat routes, one orchestrator. Three thin routes — /api/ai/chatbot, /api/ai/deskbot, /api/ai/showcase/rag — set an explicit surface and share one entry guard (guardAiRequest), then call the single orchestrateChat (routing, retrieval, tools, persistence). They replace the former single /api/ai/chat; the bare /api/ai/chat/stream is also gone. See blueprint/ai/surfaces.md.

5. Blueprint examples lag the SDK. multi-client-core.md shows AI SDK v4/v5 spellings (parameters, maxSteps, maxTokens). The running code is v6 (inputSchema, stopWhen: stepCountIs, maxOutputTokens). The code is correct; the blueprint doc has not been updated.

Related Docs