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
│
├── /showcases                       # Living demos
│   ├── +page.svelte                 # Landing with recommended path
│   ├── /shell                       # App shell features
│   │   ├── /theme                   # 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
│   │   └── /panes
│   │       ├── /panels              # Dock system (tabs, splits, activity bar)
│   │       ├── /resizable           # PaneForge resize primitives
│   │       └── /reorderable         # Drag-to-reorder panes
│   ├── /forms                       # 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
│   ├── /db                          # Database showcases
│   │   ├── /relational              # PostgreSQL (Neon)
│   │   │   ├── /connection          # Health check + latency
│   │   │   ├── /types               # Full type system demo
│   │   │   └── /mutability          # CRUD, versioning, soft delete
│   │   ├── /graph                   # Graph database (Neo4j Aura)
│   │   │   ├── /connection          # Health check + stats
│   │   │   ├── /model               # Labels, relationships, graph viz
│   │   │   └── /traversal           # Path finding, recommendations
│   │   ├── /storage                 # Object storage (Cloudflare R2)
│   │   │   ├── /connection          # Bucket health + stats
│   │   │   ├── /objects             # List, inspect, presigned downloads
│   │   │   └── /transfer            # Presigned upload, byte-range reads
│   │   └── /cache                   # Cache layer (Redis/Upstash)
│   │       ├── /connection          # Cache health check
│   │       ├── /ephemeral           # Short-lived keys, TTL
│   │       └── /patterns            # Caching strategies
│   ├── /ai                          # AI integration
│   │   ├── /connection              # Provider health + config
│   │   ├── /chat                    # Basic chat interface
│   │   ├── /streaming               # Streaming text responses
│   │   └── /retrieval               # RAG pipeline
│   │       ├── /ingest              # Document ingestion
│   │       ├── /chat                # RAG-augmented chat
│   │       ├── /contextual          # Contextual retrieval
│   │       ├── /parent-child        # Parent-child chunking
│   │       └── /graph               # Graph-based retrieval
│   ├── /auth                        # Authentication showcase
│   │   ├── /connection              # Provider health check
│   │   ├── /security                # Security features demo
│   │   └── /session                 # Session inspection
│   ├── /i18n                        # Internationalization
│   ├── /jobs                        # Background jobs
│   ├── /viz                         # Data visualization
│   │   ├── /charts                  # Chart types
│   │   ├── /plots                   # Plot types
│   │   ├── /graphs                  # Graph/network viz
│   │   ├── /diagrams                # Diagram types
│   │   └── /maps                    # Map visualizations
│   └── /3d                          # 3D experiences (Threlte + Three.js)
│       ├── /static-scene            # Static 3D scene
│       └── /animated-scene          # Animated 3D scene
│
├── /app                             # Protected area
│   ├── /dashboard                   # User home
│   ├── /settings                    # Preferences
│   └── /account                     # GDPR (export, delete)
│
├── /auth                            # Authentication
│   ├── /login                       # Email entry + OAuth
│   └── /verify                      # OTP code entry
│
└── /docs                            # Static documentation
    ├── /stack                       # Technology decisions
    └── /architecture                # Codebase structure

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/app/
├── +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/app/+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="/app/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)

The showcase landing page provides first-time visitors with a clear entry point and recommended learning path.

Purpose:

• Prevent decision paralysis (10+ demos can overwhelm)
• Guide new users through fundamentals first
• Show progress/completion status

Page content:

• Brief intro to the showcase concept
• Recommended path with categorization
• Visual cards for each section
• Optional: visited/completed indicators

Recommended Learning Path:

/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/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 basic chat through full RAG pipelines.

Sub-pages:

/showcases/auth

Authentication showcase using Better Auth. Demonstrates connection health, security features, and session state.

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/viz

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

Sub-pages:

/showcases/3d

3D experiences with Threlte and Three.js.

Sub-pages:

Protected Pages

/app/*

All routes under /app require authentication.

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

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

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

/app/dashboard

User's authenticated home.

/app/settings

User configuration (preferences & settings) with form handling.

/app/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

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
│
├── showcases/
│   ├── +page.svelte                  # Showcase landing
│   ├── +error.svelte                 # Showcase error boundary
│   ├── shell/                        # App shell features
│   │   ├── theme/+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
│   │   └── panes/
│   │       ├── panels/+page.svelte
│   │       ├── resizable/+page.svelte
│   │       └── reorderable/+page.svelte
│   ├── forms/
│   │   ├── 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
│   ├── db/                           # Database showcases
│   │   ├── relational/
│   │   │   ├── connection/+page.svelte
│   │   │   ├── types/+page.svelte
│   │   │   └── mutability/+page.svelte
│   │   ├── graph/
│   │   │   ├── connection/+page.svelte
│   │   │   ├── model/+page.svelte
│   │   │   └── traversal/+page.svelte
│   │   ├── storage/
│   │   │   ├── connection/+page.svelte
│   │   │   ├── objects/+page.svelte
│   │   │   └── transfer/+page.svelte
│   │   └── cache/
│   │       ├── connection/+page.svelte
│   │       ├── ephemeral/+page.svelte
│   │       └── patterns/+page.svelte
│   ├── ai/
│   │   ├── connection/+page.svelte
│   │   ├── chat/+page.svelte
│   │   ├── streaming/+page.svelte
│   │   └── retrieval/
│   │       ├── ingest/+page.svelte
│   │       ├── chat/+page.svelte
│   │       ├── contextual/+page.svelte
│   │       ├── parent-child/+page.svelte
│   │       └── graph/+page.svelte
│   ├── auth/
│   │   ├── connection/+page.svelte
│   │   ├── security/+page.svelte
│   │   └── session/+page.svelte
│   ├── i18n/+page.svelte
│   ├── jobs/+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
│
├── app/
│   ├── +layout.server.ts             # Auth guard
│   ├── dashboard/+page.svelte
│   ├── settings/+page.svelte
│   └── account/
│       ├── +page.svelte
│       ├── export/+server.ts
│       └── delete/+page.svelte
│
├── auth/
│   ├── login/+page.svelte
│   └── verify/+page.svelte
│
└── docs/
    ├── +layout.ts                    # prerender = true
    └── [slug]/+page.svelte           # Markdown renderer

Navigation

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

Showcase Sidebar

┌────────────────────┐
│ Showcase           │
├────────────────────┤
│ Shell              │
│   └ Theme          │
│   └ Sidebar        │
│   └ Modals         │
│   └ Toasts         │
│   └ Shortcuts      │
│   └ Errors         │
│   └ Session        │
│ UI                 │
│   └ Components     │
│   └ Decorative     │
│   └ Typography     │
│   └ Layouts        │
│   └ Tokens         │
│   └ Panes          │
│ Forms              │
│   └ Basics         │
│   └ Validation     │
│   └ Advanced       │
│   └ Patterns       │
│ DB                 │
│   └ Relational     │
│   └ Graph          │
│   └ Storage        │
│   └ Cache          │
│ AI                 │
│   └ Chat           │
│   └ Streaming      │
│   └ Retrieval      │
│ Auth               │
│ i18n               │
│ Jobs               │
│ Viz                │
│ 3D                 │
└────────────────────┘

Summary

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