Page Architecture

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

Concept

Every showcase page serves three purposes:

No documentation drift. No stale examples. The template validates itself.

Route Structure

/                                    # Landing page
│
├── /offline                         # Offline fallback (prerendered, top-level)
├── /manifest.webmanifest            # Web app manifest (+server.ts, localized)
│
├── /showcases                       # Living demos
│   ├── +page.svelte                 # Landing with recommended path
│   ├── /shell                       # App shell features
│   │   ├── /style                   # Design tokens, dark/light mode
│   │   ├── /sidebar                 # Sidebar navigation
│   │   ├── /modals                  # Modal dialogs
│   │   ├── /toasts                  # Toast notifications
│   │   ├── /shortcuts               # Keyboard shortcuts
│   │   ├── /errors                  # Error boundaries
│   │   └── /session                 # Session state
│   ├── /ui                          # Component gallery
│   │   ├── /components
│   │   │   ├── /primitives          # Buttons, inputs, badges
│   │   │   └── /composites          # Alerts, cards, menus
│   │   ├── /decorative
│   │   │   ├── /backgrounds         # Background patterns
│   │   │   └── /ornaments           # Decorative elements
│   │   ├── /typography              # Headings, body, lead
│   │   ├── /layouts                 # Stack, cluster, grid
│   │   ├── /tokens                  # Colors, spacing, shadows
│   │   ├── /menus                   # Dropdown, context, menubar
│   │   ├── /tables                  # Data tables
│   │   ├── /workbench               # Dock workspace (tabs, activity bar)
│   │   └── /splits
│   │       ├── /resizable           # PaneForge resize primitives
│   │       └── /reorderable         # Drag-to-reorder panes
│   ├── /forms                       # Form patterns
│   │   ├── /auth                    # Auth-style form patterns
│   │   ├── /basics
│   │   │   ├── /contact             # Simple contact form
│   │   │   └── /settings            # Settings form
│   │   ├── /validation
│   │   │   ├── /realtime            # Client-side live validation
│   │   │   ├── /async               # Async field validation
│   │   │   └── /server              # Server-side validation errors
│   │   ├── /advanced
│   │   │   ├── /confirm             # Confirmation dialogs
│   │   │   ├── /edit                # Edit-in-place
│   │   │   └── /reset               # Form reset patterns
│   │   └── /patterns
│   │       ├── /dependent           # Dependent field logic
│   │       ├── /dynamic             # Dynamic field lists
│   │       └── /wizard              # Multi-step wizard
│   ├── /cycle                       # End-to-end create/read/update/delete cycle
│   │   ├── /api                     # CRUD via API
│   │   ├── /form                    # CRUD via forms
│   │   └── /ai                      # CRUD via AI tool calls
│   ├── /db                          # Database showcases
│   │   ├── /relational              # PostgreSQL (Neon)
│   │   │   ├── /types               # Full type system demo
│   │   │   ├── /mutability          # CRUD, versioning, soft delete
│   │   │   └── /connection          # Health check + latency
│   │   ├── /graph                   # Graph database (Neo4j Aura)
│   │   │   ├── /model               # Labels, relationships, graph viz
│   │   │   ├── /traversal           # Path finding, recommendations
│   │   │   └── /connection          # Health check + stats
│   │   ├── /storage                 # Object storage (Cloudflare R2)
│   │   │   ├── /objects             # List, inspect, presigned downloads
│   │   │   ├── /transfer            # Presigned upload, byte-range reads
│   │   │   └── /connection          # Bucket health + stats
│   │   └── /cache                   # Cache layer (Redis/Upstash)
│   │       ├── /patterns            # Caching strategies
│   │       ├── /ephemeral           # Short-lived keys, TTL
│   │       └── /connection          # Cache health check
│   ├── /ai                          # AI integration
│   │   ├── /chat                    # Basic streaming chat interface
│   │   ├── /image-metadata          # Vision: AI proposes metadata, human approves
│   │   │   └── /analyze             # Run a single image analysis
│   │   └── /retrieval               # RAG pipeline
│   │       ├── /rag-chat            # RAG-augmented chat
│   │       ├── /explorer            # Inspect chunks, embeddings, scores
│   │       └── /ingest              # Document ingestion
│   ├── /toolkits                    # Bundled multi-step tools
│   │   └── /image-kit               # Metadata + AI cropper + embedder (no persistence)
│   │       ├── /vision              # AI metadata reader
│   │       ├── /embed               # Image/text embedder
│   │       ├── /crop                # AI frame-cropper
│   │       └── /discard             # Clear and reset the session
│   ├── /auth                        # Authentication showcase
│   │   ├── /authn                   # Authentication: sign-in, sessions
│   │   ├── /authz                   # Authorization: roles, route guards
│   │   └── /users                   # User management
│   ├── /admin                       # Operator transparency (single page)
│   ├── /privacy                     # Data-protection surface
│   │   ├── /data                    # Stored-data inventory
│   │   ├── /retention               # Retention policies
│   │   ├── /rights                  # GDPR rights (access, export, erase)
│   │   └── /cookies                 # Cookie inventory and consent
│   ├── /analytics                   # Privacy-aware analytics
│   │   ├── /overview                # Metrics summary
│   │   ├── /live                    # Real-time activity
│   │   ├── /funnels                 # Conversion funnels
│   │   ├── /journeys                # User journey paths
│   │   ├── /my-data                 # Per-user data view
│   │   └── /privacy                 # Privacy controls, opt-out
│   ├── /abuse                       # Abuse prevention
│   │   ├── /rate-limits             # Rate limiting
│   │   ├── /captcha                 # CAPTCHA challenge
│   │   ├── /honeypot                # Honeypot field trap
│   │   └── /ai-budget               # AI spend caps
│   ├── /notifications               # Notification delivery
│   │   ├── /send                    # Send a notification
│   │   ├── /channels                # Channel configuration
│   │   └── /pipeline                # Delivery pipeline
│   ├── /i18n                        # Internationalization
│   ├── /jobs                        # Background jobs
│   ├── /pwa                         # Installable app shell: manifest, SW, offline, push
│   ├── /viz                         # Data visualization
│   │   ├── /charts                  # Chart types
│   │   ├── /plots                   # Plot types
│   │   ├── /graphs                  # Graph/network viz
│   │   ├── /diagrams                # Diagram types
│   │   └── /maps                    # Map visualizations
│   └── /3d                          # 3D experiences (Threlte 8)
│       ├── /static-scene            # Static 3D scene
│       ├── /animated-scene          # Animated 3D scene (useTask)
│       ├── /customize               # Configure a model
│       │   └── /[model]             # Per-model customizer
│       └── /[model]                 # Per-model viewer
│
├── /account                         # Protected personal area (4 tabs)
│   ├── /dashboard                   # User home
│   ├── /settings                    # Preferences + data & danger zone
│   ├── /notifications               # Notification center (+ /settings)
│   ├── /security                    # Passkeys, TOTP, sessions
│   └── /data                        # GDPR transparency mirror (export)
│
├── /auth                            # Authentication
│   ├── /login                       # Email entry + OAuth
│   └── /verify                      # OTP code entry
│
└── /docs                            # Static documentation
    ├── /blueprint                   # System patterns ([...slug])
    ├── /foundation                  # Project goals ([slug])
    ├── /programming                 # Language/runtime notes ([slug])
    └── /stack                       # Technology decisions ([slug])

Error Boundary Structure

Every route group should have an +error.svelte file for graceful error handling.

Required Error Boundaries

Error Boundary File Structure

src/routes/
├── +error.svelte              # Root fallback (REQUIRED)
├── +layout.svelte
│
├── auth/
│   ├── +error.svelte          # Auth-specific errors
│   ├── login/+page.svelte
│   └── verify/+page.svelte
│
├── showcase/
│   ├── +error.svelte          # Showcase-specific errors
│   ├── +layout.svelte
│   └── ...
│
└── app/
    ├── +error.svelte          # App-specific (maintains shell)
    ├── +layout.svelte
    ├── dashboard/+page.svelte
    └── settings/
        ├── +error.svelte      # Optional: settings-specific
        └── +page.svelte

Layout Error Gotcha

⚠️ Important: Errors in +layout.server.ts are caught by +error.svelte above the layout, not next to it.

routes/[[locale=locale]]/account/
├── +layout.server.ts   ← Error here
├── +layout.svelte
└── +error.svelte       ← Won't catch it!

routes/
└── +error.svelte       ← Catches it here (parent level)

Error Page Implementation

<!-- src/routes/+error.svelte (Root) -->
<script>
  import { page } from '$app/state';
</script>

<div class="error-page">
  <h1>{page.status}</h1>
  <p>{page.error?.message || 'Something went wrong'}</p>
  <a href="/">Go home</a>
</div>

<!-- src/routes/[[locale=locale]]/account/+error.svelte (App area - keeps shell) -->
<script>
  import { page } from '$app/state';
</script>

<!-- This renders inside AppShell layout -->
<div class="error-content">
  <h1>Error {page.status}</h1>
  <p>{page.error?.message || 'Something went wrong'}</p>
  <a href="/account/dashboard">Back to dashboard</a>
</div>

Component-Level Errors (Svelte 5)

Use <svelte:boundary> for component rendering errors:

<svelte:boundary onerror={(error) => logToSentry(error)}>
  <ComplexChart data={chartData} />

  {#snippet failed(error, reset)}
    <div class="error-state">
      <p>Chart failed to load</p>
      <button onclick={reset}>Retry</button>
    </div>
  {/snippet}
</svelte:boundary>

Limitations: Only catches rendering/effect errors, not event handlers or async code.

Showcase Pages

/showcases (Landing Page)

Entry point into all 19 showcase cards, grouped into five domain sections derived from each card's domain field (groupByDomain() in the registry).

Page content:

• Sticky PageHeader (title + description), height bound for anchor scroll-margin
• Jump-nav linking to each domain section's anchor
• One <section> per domain, cards rendered as LinkCards (icon, title, description, sublinks) in a NavGrid

Domains (registry order):

/showcases/shell

App shell features: theming, navigation, overlays, and session.

Sub-pages:

/showcases/ui

Component gallery covering every UI primitive and composite.

Sub-pages:

/showcases/forms

Form handling with validation and progressive enhancement.

Sub-pages:

Demonstrates:

<!-- Client -->
<form method="POST" use:enhance>
  <input name="email" bind:value={$form.email} />
  {#if $errors.email}<span>{$errors.email}</span>{/if}
  <button disabled={$submitting}>Submit</button>
</form>

// +page.server.ts
export const actions = {
  default: async ({ request }) => {
    const form = await superValidate(request, valibot(schema));
    if (!form.valid) return fail(400, { form });
    // Process...
    return { form };
  }
};

/showcases/cycle

End-to-end create/read/update/delete cycle, demonstrated three ways over the same entity.

Sub-pages:

/showcases/db/relational

PostgreSQL showcase using Neon serverless. Three sub-pages under the DB hub.

Sub-pages:

/showcases/db/graph

Graph database showcase using Neo4j Aura.

Sub-pages:

/showcases/db/storage

Object storage showcase (Cloudflare R2). Three sub-pages under the DB hub.

Sub-pages:

Upload flow:

Client                    Server                    R2
  │                         │                        │
  ├── Request upload URL ──▶│                        │
  │                         ├── Validate + presign ─▶│
  │◀── Presigned PUT URL ───┤                        │
  │                         │                        │
  ├── PUT file directly ────┼───────────────────────▶│
  │                         │                        │
  ├── Confirm upload ──────▶│                        │
  │                         ├── HeadObject verify ──▶│
  │◀── Upload result ───────┤                        │

/showcases/db/cache

Cache layer showcase. Three sub-pages covering connection, ephemeral keys, and caching strategies.

Sub-pages:

/showcases/ai

AI integration showcase using the Vercel AI SDK. Covers streaming chat, vision-driven metadata, and the RAG retrieval pipeline.

Sub-pages:

/showcases/toolkits

Bundled, multi-step tools: upload once, run an AI pipeline, adjust the results, then approve. Nothing is saved. The first toolkit is Image Kit.

Sub-pages:

/showcases/auth

Authentication showcase using Better Auth. Demonstrates authentication, authorization, and user management.

Sub-pages:

/showcases/admin

Operator transparency: what the single admin can see and do, and the code-enforced guarantees that limit it. Single page, no sub-routes.

/showcases/privacy

The data-protection surface: controller, lawful basis, retention, and your rights.

Sub-pages:

/showcases/analytics

Privacy-aware analytics: metrics with per-user transparency and opt-out.

Sub-pages:

/showcases/abuse

Abuse prevention: rate limiting, bot defenses, and AI spend caps.

Sub-pages:

/showcases/notifications

Notification delivery: send, channel routing, and the delivery pipeline.

Sub-pages:

/showcases/i18n

Internationalization with Paraglide JS. Single page covering the full i18n feature set.

Page content:

• Language switcher
• Translated strings
• Pluralization examples
• Date/number formatting
• RTL support demo

/showcases/jobs

Background job patterns. Single page demonstrating job scheduling and status tracking.

/showcases/pwa

Installable app shell: manifest, service worker, offline fallback, update flow, and web push. Single page — the living demo for blueprint/pwa.md.

/showcases/viz

Data visualization hub. Five sub-pages covering the full range of chart and diagram types.

Sub-pages:

/showcases/3d

3D experiences with Threlte 8. No vanilla Three.js render loop and no physics engine.

Sub-pages:

Protected Pages

/account/*

All routes under /account require authentication.

Protection per-route (not layout - see auth.md):

// /account/dashboard/+page.server.ts
import { requireAuth } from '$lib/server/auth/guard';

export async function load(event) {
  const { user } = await requireAuth(event);
  return { user };
}

/account/dashboard

User's authenticated home.

/account/settings

User configuration (preferences & settings) with form handling.

/account

GDPR compliance routes.

Auth Pages

/auth/login

Flow: User enters email → receives email with both magic link AND OTP code → chooses how to authenticate.

/auth/verify

PWA Routes

Top-level — outside the locale tree, supporting the installable app shell. See blueprint/pwa.md for the full design.

Static Documentation

/docs/*

Pre-rendered documentation pages.

// /docs/+layout.ts
export const prerender = true;

Markdown content rendered with syntax highlighting.

File Structure

src/routes/
├── +layout.svelte                    # Root layout
├── +layout.server.ts                 # Auth check, theme
├── +page.svelte                      # Landing
│
├── offline/+page.svelte               # Offline fallback (prerendered)
├── manifest.webmanifest/+server.ts    # Web app manifest
│
├── showcases/
│   ├── +page.svelte                  # Showcase landing
│   ├── +error.svelte                 # Showcase error boundary
│   ├── shell/                        # App shell features
│   │   ├── style/+page.svelte
│   │   ├── sidebar/+page.svelte
│   │   ├── modals/+page.svelte
│   │   ├── toasts/+page.svelte
│   │   ├── shortcuts/+page.svelte
│   │   ├── errors/+page.svelte
│   │   └── session/+page.svelte
│   ├── ui/                           # Component gallery
│   │   ├── components/
│   │   │   ├── primitives/+page.svelte
│   │   │   └── composites/+page.svelte
│   │   ├── decorative/
│   │   │   ├── backgrounds/+page.svelte
│   │   │   └── ornaments/+page.svelte
│   │   ├── typography/+page.svelte
│   │   ├── layouts/+page.svelte
│   │   ├── tokens/+page.svelte
│   │   ├── menus/+page.svelte
│   │   ├── tables/+page.svelte
│   │   ├── workbench/+page.svelte
│   │   └── splits/
│   │       ├── resizable/+page.svelte
│   │       └── reorderable/+page.svelte
│   ├── forms/
│   │   ├── auth/+page.svelte
│   │   ├── basics/
│   │   │   ├── contact/+page.svelte
│   │   │   └── settings/+page.svelte
│   │   ├── validation/
│   │   │   ├── realtime/+page.svelte
│   │   │   ├── async/+page.svelte
│   │   │   └── server/+page.svelte
│   │   ├── advanced/
│   │   │   ├── confirm/+page.svelte
│   │   │   ├── edit/+page.svelte
│   │   │   └── reset/+page.svelte
│   │   └── patterns/
│   │       ├── dependent/+page.svelte
│   │       ├── dynamic/+page.svelte
│   │       └── wizard/+page.svelte
│   ├── cycle/
│   │   ├── api/+page.svelte
│   │   ├── form/+page.svelte
│   │   └── ai/+page.svelte
│   ├── db/                           # Database showcases
│   │   ├── relational/
│   │   │   ├── types/+page.svelte
│   │   │   ├── mutability/+page.svelte
│   │   │   └── connection/+page.svelte
│   │   ├── graph/
│   │   │   ├── model/+page.svelte
│   │   │   ├── traversal/+page.svelte
│   │   │   └── connection/+page.svelte
│   │   ├── storage/
│   │   │   ├── objects/+page.svelte
│   │   │   ├── transfer/+page.svelte
│   │   │   └── connection/+page.svelte
│   │   └── cache/
│   │       ├── patterns/+page.svelte
│   │       ├── ephemeral/+page.svelte
│   │       └── connection/+page.svelte
│   ├── ai/
│   │   ├── chat/+page.svelte
│   │   ├── image-metadata/
│   │   │   ├── +page.svelte
│   │   │   └── analyze/+page.svelte
│   │   └── retrieval/
│   │       ├── +page.svelte
│   │       ├── rag-chat/+page.svelte
│   │       ├── explorer/+page.svelte
│   │       └── ingest/+page.svelte
│   ├── toolkits/
│   │   └── image-kit/
│   │       ├── +page.svelte
│   │       ├── vision/+page.svelte
│   │       ├── embed/+page.svelte
│   │       ├── crop/+page.svelte
│   │       └── discard/+page.svelte
│   ├── auth/
│   │   ├── authn/+page.svelte
│   │   ├── authz/+page.svelte
│   │   └── users/+page.svelte
│   ├── admin/+page.svelte
│   ├── privacy/
│   │   ├── data/+page.svelte
│   │   ├── retention/+page.svelte
│   │   ├── rights/+page.svelte
│   │   └── cookies/+page.svelte
│   ├── analytics/
│   │   ├── overview/+page.svelte
│   │   ├── live/+page.svelte
│   │   ├── funnels/+page.svelte
│   │   ├── journeys/+page.svelte
│   │   ├── my-data/+page.svelte
│   │   └── privacy/+page.svelte
│   ├── abuse/
│   │   ├── rate-limits/+page.svelte
│   │   ├── captcha/+page.svelte
│   │   ├── honeypot/+page.svelte
│   │   └── ai-budget/+page.svelte
│   ├── notifications/
│   │   ├── send/+page.svelte
│   │   ├── channels/+page.svelte
│   │   └── pipeline/+page.svelte
│   ├── i18n/+page.svelte
│   ├── jobs/+page.svelte
│   ├── pwa/+page.svelte
│   ├── viz/
│   │   ├── +page.svelte
│   │   ├── charts/+page.svelte
│   │   ├── plots/+page.svelte
│   │   ├── graphs/+page.svelte
│   │   ├── diagrams/+page.svelte
│   │   └── maps/+page.svelte
│   └── 3d/
│       ├── +page.svelte
│       ├── static-scene/+page.svelte
│       ├── animated-scene/+page.svelte
│       ├── customize/
│       │   ├── +page.svelte
│       │   └── [model]/+page.svelte
│       └── [model]/+page.svelte
│
├── app/
│   ├── +layout.server.ts             # Auth guard
│   ├── dashboard/+page.svelte
│   ├── settings/+page.svelte
│   └── account/
│       ├── +page.svelte
│       ├── data/+page.svelte         # View stored data
│       └── security/+page.svelte     # Sessions, passkeys, deletion
│
├── auth/
│   ├── login/+page.svelte
│   └── verify/+page.svelte
│
└── docs/
    ├── blueprint/[...slug]/+page.svelte    # Markdown renderer (+page.server.ts)
    ├── foundation/[slug]/+page.svelte
    ├── programming/[slug]/+page.svelte
    └── stack/[slug]/+page.svelte

Navigation

No global header. Navigation lives in the sidebar. See app-shell/ for details.

Showcase Sidebar

┌────────────────────┐
│ Showcase           │
├────────────────────┤
│ Shell              │
│   └ Style          │
│   └ Sidebar        │
│   └ Modals         │
│   └ Toasts         │
│   └ Shortcuts      │
│   └ Errors         │
│   └ Session        │
│ UI                 │
│   └ Components     │
│   └ Decorative     │
│   └ Typography     │
│   └ Layouts        │
│   └ Tokens         │
│   └ Menus          │
│   └ Tables         │
│   └ Workbench      │
│   └ Splits         │
│ Forms              │
│   └ Auth           │
│   └ Basics         │
│   └ Validation     │
│   └ Advanced       │
│   └ Patterns       │
│ Cycle              │
│   └ API            │
│   └ Form           │
│   └ AI             │
│ DB                 │
│   └ Relational     │
│   └ Graph          │
│   └ Storage        │
│   └ Cache          │
│ AI                 │
│   └ Chat           │
│   └ Image Metadata │
│   └ Retrieval      │
│ Toolkits           │
│   └ Image Kit      │
│ Auth               │
│   └ Authn          │
│   └ Authz          │
│   └ Users          │
│ Admin              │
│ Privacy            │
│   └ Data           │
│   └ Retention      │
│   └ Rights         │
│   └ Cookies        │
│ Analytics          │
│ Abuse              │
│ Notifications      │
│ i18n               │
│ Jobs               │
│ Pwa                │
│ Viz                │
│ 3D                 │
└────────────────────┘

Summary

The showcase pages form a comprehensive test suite. If all pages render correctly, the entire stack works.