Blueprint — Docs

3d

3D Quick Reference

Copy-paste starting points for Threlte 8 in v10r. Threlte only — no vanilla Three.js.

3D Web Integration

How v10r wires Threlte into SvelteKit.

Asset Production

A structured, validated request becomes a checked 3D asset: parametric geometry built in code, inspected, written as GLB with its provenance inside, measured, optionally kept in a…

Product Composition

Typed, reusable 3D products with connection ports, joined into an editable assembly: a heating system of boiler, pump and radiators, or a shelf of uprights and boards.

abuse

AI Daily Token Budget

Per-user daily token cap that prevents cost-amplification abuse. A single authenticated user cannot exhaust the AI quota for all other users by running many expensive requests.

ALTCHA Captcha

Proof-of-work captcha using altcha-lib. The client solves a CPU-bound puzzle; the server verifies the HMAC-signed payload.

Honeypot

Two-signal bot detection that requires no user interaction: a hidden field that bots fill and a minimum-fill-time check that bots fail.

Rate Limits

Sliding-window rate limits backed by Upstash Redis.

admin

Cross-Device Debug Pairing

Admin tests the public site on a real phone without a second login.

ai

AI Cost Monitoring

Cross-surface AI-spend monitoring, served on the admin Cost tab (/admin/ai/cost).

AI Surfaces: chatbot & deskbot

The AI subsystem serves two product surfaces through one orchestrator. They are told apart by an explicit surface discriminant — not by implicit request-flag truthiness.

Assistant profiles

> Status: BUILT 2026-09-12 (Phase 2 of the AI context + trace refactor, docs/ai-ref-plan.md), > validate-green, dev/uncommitted.

Desk + AI Integration Architecture

Final architectural recommendation for integrating AI tool-calling into the Desk workspace.

Evals

How v10r guards AI answer quality the way it guards bundle size: a committed golden set, a deterministic grader per fact, and a floor the pass rate must hold.

Graph RAG

Hybrid retrieval combining knowledge graphs (Neo4j) with vector embeddings for more accurate, explainable AI responses.

Grounded retrieval

One retrieve() kernel, two profiles over two corpora, one ingest-built corpus map.

Harness Lens

"Harness" is a lens we use to audit the bot's post-prompt-dispatch machinery — not a module.

Image Kit

One image, three AI tools, one flow: upload → Run → adjust → Approve. Lands as the first page of the toolkits showcase collection at /showcases/toolkits/image-kit.

Image Metadata Reader

A vision model proposes metadata for an uploaded image; the human reviews and approves before anything persists.

Knowledge Base & Retrieval

How v10r organizes the knowledge its chatbot answers from, and how it retrieves it.

Persistent / Minimizable Chatbot

> Status: BUILT + browser-verified, 2026-06-27 (dev, uncommitted).

Provider & Model Routing

Where provider configuration lives, how the orchestrator selects a provider per turn — and why it matters for tool reliability.

RAG Roadmap — the two LLM-amplifying retrieval features

> 2026-09-12: the third spec this doc carried — an LLM-compiled page layer with a nightly recompile loop — was dropped with the layer it built on (Phase 4 of docs/ai-ref-plan.md…

Site-aware chatbot (Vely knows where you are)

> Status: v1 BUILT + VALIDATE-GREEN + BROWSER-VERIFIED LIVE, 2026-06-27 (dev, UNCOMMITTED).

TOON (Token-Oriented Object Notation)

Compact serialization format optimized for LLM input. Reduces tokens by 30-60% compared to JSON.

Turn trace

> Status: BUILT 2026-09-12 (Phases 1, 3 and 5 of the AI context + trace refactor), > validate-green; the turn graph and the recorded ancestry landed 2026-09-13; the >…

Untrusted content

How v10r keeps a document a user ingested from steering the assistant that reads it — the "lethal trifecta" of prompt injection, and the code that holds each of its three legs.

analytics

Analytics Collector — Active

analyticsCollector is wired into the sequence(...) in src/hooks.server.ts at the final position in the chain.

DPIA screening — analytics

GDPR Art 35(1) requires a Data Protection Impact Assessment where processing is "likely to result in a high risk" to data subjects.

Legitimate Interest Assessment — anonymous analytics lane

Covers analytics.events + analytics.sessions — the anonymous lane, keyed by SHA256(ip:ua).

The lane model (anonymous · authenticated · bot)

Analytics is split into lanes that share no identifier and no join key.

app-shell

AI Assistant

The Vely chatbot: a persistent, minimizable, non-modal assistant docked beside the page content.

Component Organization

Rules for organizing components using the Atomic Design pattern: atoms → molecules → organisms → templates.

Empty States

UI patterns for when there's no data to display. Critical for first-run experience and edge cases.

Keyboard Shortcuts

Central registry for all keyboard shortcuts in the app shell. Enables discoverability, conflict resolution, and accessibility.

Layout

The app shell layout, breakpoints, z-index layers, and accessibility requirements.

Loading States

Visual feedback during data fetching and navigation. Critical for perceived performance and user confidence.

Navigation

Progressive Disclosure with hierarchical navigation. Users land on pages with a single click; subpages/sections are revealed via dropdown.

Notifications

In-app notification system with a full-page notification center, preference management, and an SSE stream (/api/notifications/stream) for clients that want live updates.

PageHeader

Per-page header inside the main content area. Not a global header — each page optionally includes this component for its title and actions.

Session Lifecycle

Managing authentication state within the app shell: session expiry, re-authentication, and graceful degradation.

Settings & Preferences

User configuration for appearance, language, privacy, and accessibility. This page covers both:

Shell State

Orchestration of state across app shell components: sidebar, modals, theme, toasts, and user session.

Sidebar

The sidebar is the primary navigation element, adapting responsively for desktop and mobile.

Toast Notifications

Ephemeral feedback messages that appear in response to user actions. Distinct from the notification center (persistent) - toasts are immediate, temporary, and action-specific.

User Account

User account management for identity, security, and GDPR compliance. High-stakes operations requiring careful UX design.

architecture

Agent Experience (AX)

How v10r serves AI agents as first-class consumers: a machine-readable docs layer, an agent-facing URL map, self-correcting MCP errors, and a loopable convention checker.

Backend Jobs Architecture

Background work in the application falls into two categories distinguished by trigger mechanism, not code structure.

External service: a separately deployed backend behind a typed client

How a SvelteKit app calls a backend that is its own process, built, deployed and scaled on its own — through one authoritative contract, one server-only service client, and a…

Hosted MCP: three trust surfaces over one domain

The local stdio Pattern MCP (see pattern-mcp.md) runs as an ephemeral container a coding agent spawns itself.

Multi-Client Core Architecture

The same backend logic must serve four client types: human UI (SvelteKit form actions and load functions), AI agents (Vercel AI SDK tool calls), external API (REST endpoints), and…

Native Client — the Fifth Client (Blueprint)

> Status: planned — not built. This documents HOW a true native mobile app would attach to the multi-client core, so the seam is proven on paper.

v10r Pattern MCP

A read-only MCP (Model Context Protocol) server that exposes v10r's pattern library to coding agents.

WebAssembly (Rust)

A Rust compute kernel compiled to wasm, vendored into the repo, benchmarked honestly against its own line-for-line JS twin.

Workers

"Worker" names three unrelated things.

data

Drizzle Workflow: Dev → Production

How to manage database schema changes across development and production environments using Drizzle ORM.

Neon Branch Refresh

Reset the dev Neon Postgres branch from its parent (production) on demand or on a schedule, with a live monitor. Admin-only, surfaced at /admin/db. Postgres/Neon only in v1.

db

Graph Database

Graph data model for relationships, navigation, and future RAG capabilities.

Polyglot Freshness

Cross-database reference integrity in a multi-store architecture.

Relational Database

Drizzle ORM schema for relational data and Better Auth integration.

design

Component Architecture

Accessible, composable UI components built on Bits UI primitives with CVA styling.

Design Tokens

Single source of truth for all design values. Defined once, referenced everywhere.

Explosive Discovery — Nested Depth

A review heuristic for a menu, toolbar or page that has grown past a handful of unrelated actions. Its motto:

Styling Architecture

Mobile-first fluid responsive design with UnoCSS.

dynamic-attributes

Dynamic Attributes — plan and progress record

The durable plan for pattern.md: the phases as planned, what each delivered, the second-pass audit and what it changed.

Dynamic Attributes — research report

Research behind pattern.md, done 2026-11-05 before any code was written.

Dynamic Attributes — self-describing records

A record that starts almost empty and grows the attributes its user names.

general

API Architecture

REST endpoints with SvelteKit +server.ts files.

Authentication Architecture

Passwordless session-based authentication using Better Auth with Drizzle ORM.

Deployment

Tri-target deployment design: Vercel (Node.js), Vercel (Bun experimental), and Koyeb (Bun container).

Error Handling

SvelteKit error handling patterns for pages, forms, and API routes.

Forms Architecture

Type-safe forms with real-time validation using Superforms and Valibot.

Internationalization Architecture

URL-based locale routing with compile-time translations using Paraglide JS v2.

Middleware

SvelteKit hooks for request interception, authentication, and cross-cutting concerns.

Name check — search aggregation over unreliable registries

A public, no-login pre-screen for a proposed brand, product or project name: what already exists that could conflict with it.

Page Architecture

Self-documenting template where each page tests the features it documents.

PWA — Installable App Shell

> Status: BUILT, 2026-07-03 (dev, uncommitted).

State Management Architecture

Svelte 5 runes for explicit, portable reactivity.

Visual Identity Architecture

> How v10r resolves a visitor's palette, typography and border-radius — and why there is deliberately no site-wide brand lock.

integrity

Derivation

Most stored data in an application is derived: chunks and embeddings from documents, generated pages from a registry, a wasm binary from a crate.

Execution

Work that outlives one request, or one tab, has to leave the world in a known state when something dies halfway through.

Truth

Two questions a reader of any fact needs answered: who owns it, and how sure are we.

notifications

Channel Connections

How users connect external notification channels (Telegram, Discord) to their account.

Notification Routing

Backend architecture for multi-channel notification delivery.

Notification Schema

Database tables for multi-channel notification system.

Notification Settings UI

Frontend architecture for channel connections and notification settings management.

pim

Product sheet workflow

How v10r turns a supplier's Excel export into a sheet a shop or PIM will import, with an AI agent doing the judgement and code doing the work.

Tutorial: a supplier export onto a shop import, with an AI agent

You receive a product export from a German supplier and need to import it into a shop that expects English attribute names, GTIN-13s, colours from a fixed list and weights in kg.

quick-search

Blog Full-Text Search

Blog search (Lane B) runs a live Postgres FTS query against blog.revision.

Search Architecture

Every search query runs two parallel, independent lanes. Results are group-stacked by surface — not RRF-fused or score-blended.

Search Indexing

The Lane-A shard is a prerendered JSON array of SearchRecord objects — titles only, no body text.

Search UI

#lib/components/composites/command-palette/

security

Gate tests

v10r's distinctive security pattern: static scans that fail the build.

Key ring

How v10r keeps credentials at rest — AI provider API keys and name-check vendor secrets — so that the key sealing them can be rotated without losing a single one.

Security topology

Where each control lives.

Threat model

Written after a multi-agent security review of the whole codebase.

testing

AI Testing Infrastructure

> Superseded in part. This document records the original design and the evidence behind > it.

Testing strategy

What earns an automated test here, what does not, and why the suite is shaped the way it is.

Geht dieses Pattern noch besser? Sag uns, wie.

Feedback geben