Skip to main content

Blueprint

Implementation patterns — how features are wired together using the stack.

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.

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 (plus one showcase demo) through one endpoint and one orchestrator.

Desk + AI Integration Architecture

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

Graph RAG

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

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. Lands as a server-backed showcase at /showcases/ai/image-metadata.

Knowledge Base & Retrieval

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

Layered RAG

Two-layer retrieval: llmwiki is the primary answer surface; rawrag is the audit and drill-down trail.

nRAG Observability

> Status: BUILT + validate-green + browser-verified-live (2026-06-27, dev, UNCOMMITTED).

Persistent / Minimizable Chatbot

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

Provider & Model Routing

How the orchestrator selects a provider per turn — and why it matters for tool reliability.

RAG Roadmap — the three LLM-amplifying retrieval features

The detailed companion to knowledge-base.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.

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 two-lane analytics model

Analytics is split into two lanes that share no identifier and no join key. The separation is the load-bearing design decision in the whole subsystem.

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 full-page notification center, preference management, and real-time 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, notifications, 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.

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.

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.

Styling Architecture

Mobile-first fluid responsive design with UnoCSS.

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: 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.

Page Architecture

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

Progressive Revelation (ProgRev) Blueprint

> Status: planned — not yet built. This document describes an intended design, not current code.

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.

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.

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.

Security topology

Where each control lives.

Threat model

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

testing

AI Testing Infrastructure

> Status: built.

← Back to Docs

Think this pattern could be better? Tell us how.

Leave feedback