SvelteKit Architecture

Overview

The Refresh App Web is built with SvelteKit 2 and Svelte 5, leveraging the latest features for server-side rendering (SSR), reactive UI, and file-based routing. The application is deployed on Cloudflare Workers using the @sveltejs/adapter-cloudflare adapter, enabling edge-based rendering globally.

SvelteKit 2 Overview

SvelteKit is a meta-framework for Svelte that provides:

• Server-Side Rendering (SSR): Pages are pre-rendered at the edge

• File-Based Routing: Routes are defined by the directory structure

• Load Functions: Type-safe data fetching on server and client

• Form Actions: Server-side form handling with progressive enhancement

• Layouts: Nested layouts for code reuse

• Hooks: Middleware-like functionality for request handling

Svelte 5 Runes

Svelte 5 introduces runes for explicit reactivity:

// State management
let count = $state(0);

// Derived state
let doubled = $derived(count * 2);

// Props (in components)
let { user, tenants } = $props();

// Effects
$effect(() => {
	console.log(`Count is now ${count}`);
});

Key Benefits:

• More explicit reactivity model

• Better TypeScript support

• Improved performance

• Easier testing

Project Structure

src/
├── routes/                         # File-based routing
│   ├── (authenticated)/           # Layout group for authenticated routes
│   │   ├── +layout.svelte         # Authenticated layout
│   │   ├── +layout.server.ts      # Server-side data loading
│   │   ├── app/                   # Main app routes
│   │   │   ├── +layout.svelte     # App shell layout
│   │   │   ├── +page.svelte       # Dashboard page
│   │   │   ├── settings/          # Settings routes
│   │   │   ├── detection/         # Detection routes
│   │   │   └── risk/              # Risk routes
│   │   └── onboarding/            # Onboarding flow
│   ├── api/                       # API routes
│   │   ├── jwks_json/+server.ts   # JWKS endpoint
│   │   └── images/+server.ts      # Image handling
│   ├── auth/                      # Authentication routes
│   │   └── +page.server.ts        # Sign-in page
│   ├── +layout.svelte             # Root layout
│   └── +error.svelte              # Error page
├── lib/
│   ├── components/                # Reusable components
│   ├── server/                    # Server-only code
│   │   ├── auth.ts                # Auth.js configuration
│   │   ├── db/                    # Database schema and queries
│   │   └── api/                   # Server-side API functions
│   └── types/                     # TypeScript types
└── hooks.server.ts                # Server-side hooks

Routing

File-Based Routing

Routes are defined by the file system:

File	Purpose	Example
+page.svelte	Page component	/app/settings → routes/app/settings/+page.svelte
+page.server.ts	Server-side load function	Data fetching, form actions
+layout.svelte	Layout component	Wraps child pages
+layout.server.ts	Layout server load	Shared data for nested routes
+server.ts	API endpoint	JSON responses, file uploads
+error.svelte	Error boundary	Custom error pages

Layout Groups

Layout groups use parentheses to organize routes without affecting URLs:

routes/
├── (authenticated)/         # Requires authentication
│   ├── +layout.svelte       # Shared authenticated layout
│   └── app/
│       └── +page.svelte     # /app (not /(authenticated)/app)
└── auth/
    └── +page.svelte         # /auth (public)

Benefits:

• Enforce authentication at layout level

• Share layouts without URL nesting

• Organize related routes

Route Parameters

Dynamic routes use [param] syntax:

routes/app/detection/team/[team_slug]/+page.server.ts

Access via params:

export const load = async ({ params }) => {
	const teamSlug = params.team_slug;
	// Fetch team data
};

Server-Side Rendering (SSR)

How SSR Works

1. Request arrives at Cloudflare edge

2. Server hooks execute (security, auth, tenant context)

3. Load function runs on server

4. Page is rendered to HTML

5. HTML sent to client with embedded data

6. Hydration occurs - Svelte takes over on client

Load Functions

Server-side load (+page.server.ts):

import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ locals, params }) => {
	const session = await locals.auth();

	if (!session?.user) {
		redirect(302, '/auth');
	}

	const tenant = session.user.activeTenant;
	const data = await fetchData(tenant.id);

	return {
		data,
		tenant
	};
};

Universal load (+page.ts) - runs on both server and client:

export const load: PageLoad = async ({ fetch, data }) => {
	const response = await fetch('/api/data');
	return {
		apiData: await response.json(),
		...data
	};
};

Form Actions

Server-side form handling with progressive enhancement:

// +page.server.ts
export const actions = {
	updateSettings: async ({ request, locals }) => {
		const session = await locals.auth();
		const formData = await request.formData();

		const name = formData.get('name');
		// Update database

		return { success: true };
	}
};

In component:

<form method="POST" action="?/updateSettings">
	<input name="name" type="text" />
	<button type="submit">Save</button>
</form>

Layouts

Nested Layouts

Layouts wrap their child routes and can be nested:

routes/
├── +layout.svelte                  # Root layout (all pages)
└── (authenticated)/
    ├── +layout.svelte              # Authenticated layout
    └── app/
        ├── +layout.svelte          # App shell (sidebar, header)
        └── settings/
            ├── +layout.svelte      # Settings layout (tabs)
            └── +page.svelte        # Settings page

Result: Settings page has 4 nested layouts.

Layout Inheritance

Child routes inherit parent layouts:

<!-- routes/+layout.svelte (root) -->
<script>
  import { ModeWatcher } from 'mode-watcher';
</script>

<ModeWatcher />
{@render children?.()}

<!-- routes/(authenticated)/+layout.svelte -->
<script>
  import { AffordanceProvider } from '$lib/components';
  const { children, data } = $props();
</script>

<AffordanceProvider>
  {@render children?.()}
</AffordanceProvider>

<!-- routes/(authenticated)/app/+layout.svelte -->
<script>
  const { children } = $props();
</script>

<div class="app-shell">
  <Sidebar />
  <main>{@render children?.()}</main>
</div>

Layout Data Loading

Layouts can load shared data:

// routes/(authenticated)/+layout.server.ts
export const load: LayoutServerLoad = async ({ locals }) => {
	const session = await locals.auth();

	return {
		sessionUser: session?.user,
		affordanceProviderData: {
			affordances: session?.user.activeTenant?.metadata?.affordances || [],
			bypassAll: session?.user.role === 'ADMIN'
		}
	};
};

Accessible in all child routes via data prop.

Hooks

Server Hooks (hooks.server.ts)

Hooks run on every request, acting as middleware:

import { sequence } from '@sveltejs/kit/hooks';
import type { Handle } from '@sveltejs/kit';

const securityHandle: Handle = async ({ event, resolve }) => {
	// HTTP → HTTPS redirect
	if (!dev && event.url.protocol === 'http:') {
		return new Response(null, {
			status: 302,
			headers: {
				Location: event.url.href.replace('http://', 'https://')
			}
		});
	}

	const response = await resolve(event);

	// Security headers
	response.headers.set('X-Content-Type-Options', 'nosniff');
	response.headers.set('X-Frame-Options', 'DENY');
	response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');

	return response;
};

export const handle = sequence(
	securityHandle,
	authHandle, // From $lib/server/auth.ts
	posthogHandle // Analytics proxy
);

Hook Sequence

Hooks execute in order:

1. Security Handle - HTTPS redirect, security headers

2. Auth Handle - Authentication, session management

3. PostHog Handle - Analytics proxy for /relay-uBFJ

Event Locals

Hooks can set event.locals for downstream use:

// In auth.ts handle
event.locals.activeTenantId = cookies.get('activeTenantId');
event.locals.auth = () => getSession(event);

// In load function
export const load = async ({ locals }) => {
	const session = await locals.auth();
	const tenantId = locals.activeTenantId;
};

Cloudflare Adapter

Configuration

svelte.config.js:

import adapter from '@sveltejs/adapter-cloudflare';

export default {
	kit: {
		adapter: adapter()
	}
};

Build Output

.svelte-kit/cloudflare/
├── _worker.js           # Cloudflare Worker entry point
├── index.html           # Prerendered fallback
└── assets/              # Static assets

Cloudflare Bindings

Access Cloudflare services via platform:

export const load: PageServerLoad = async ({ platform }) => {
	const bucket = platform?.env?.IMAGES_BUCKET;

	// Upload to R2
	await bucket.put('key', data);
};

wrangler.toml:

[[r2_buckets]]
binding = "IMAGES_BUCKET"
bucket_name = "development"

Type Safety

Generated Types

SvelteKit generates types for routes:

import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ params }) => {
	// `params` type is inferred from route structure
	const slug = params.team_slug; // Type: string

	return {
		team: { id: '1', name: 'Engineering' }
	};
};

In component:

<script lang="ts">
	import type { PageData } from './$types';

	const { data }: { data: PageData } = $props();
	// `data.team` is fully typed
</script>

App Type Declaration

src/app.d.ts:

declare global {
	namespace App {
		interface Locals {
			auth: () => Promise<Session | null>;
			activeTenantId?: string;
			activeUserId?: string;
		}

		interface Platform {
			env: {
				IMAGES_BUCKET: R2Bucket;
			};
		}
	}
}

export {};

Performance Optimizations

Code Splitting

vite.config.ts:

export default defineConfig({
	build: {
		rollupOptions: {
			output: {
				manualChunks: (id) => {
					if (id.includes('node_modules')) {
						if (id.includes('svelte')) return 'vendor';
						if (id.includes('lucide') || id.includes('bits-ui')) return 'ui';
						if (id.includes('d3') || id.includes('chart.js')) return 'charts';
						return 'vendor';
					}
				}
			}
		}
	}
});

Lazy Loading

<script>
	import { browser } from '$app/environment';

	let HeavyComponent;

	$effect(() => {
		if (browser) {
			import('$lib/components/HeavyComponent.svelte').then(
				(module) => (HeavyComponent = module.default)
			);
		}
	});
</script>

{#if HeavyComponent}
	<svelte:component this={HeavyComponent} />
{/if}

Preloading

<a href="/dashboard" data-sveltekit-preload-data="hover"> Dashboard </a>

Error Handling

Error Pages

routes/+error.svelte:

<script>
	import { page } from '$app/stores';
</script>

<h1>{$page.status}</h1><p>{$page.error?.message}</p>

Error Boundaries

// In load function
export const load = async () => {
	const data = await fetchData();

	if (!data) {
		throw error(404, 'Not found');
	}

	return { data };
};

Global Error Handler

hooks.server.ts:

export const handleError = async ({ error }) => {
	// Log to PostHog
	const client = new PostHog(env.PUBLIC_POSTHOG_API_KEY);
	client.captureException(error);
	await client.shutdown();
};

Testing

Component Testing

import { render, screen } from '@testing-library/svelte';
import MyComponent from './MyComponent.svelte';

test('renders correctly', () => {
	render(MyComponent, { props: { name: 'World' } });
	expect(screen.getByText('Hello World')).toBeInTheDocument();
});

Vitest Configuration

vite.config.ts:

test: {
	workspace: [
		{
			name: 'client',
			environment: 'jsdom',
			include: ['src/**/*.svelte.{test,spec}.{js,ts}'],
			exclude: ['src/lib/server/**']
		},
		{
			name: 'server',
			environment: 'node',
			include: ['src/**/*.{test,spec}.{js,ts}'],
			exclude: ['src/**/*.svelte.{test,spec}.{js,ts}']
		}
	];
}

Best Practices

1. Use Server-Side Load Functions

Fetch data on the server for better performance and SEO:

// ✅ Good - server-side
export const load: PageServerLoad = async () => {
	const data = await db.query.users.findMany();
	return { users: data };
};

// ❌ Avoid - client-side fetch
onMount(async () => {
	const response = await fetch('/api/users');
	users = await response.json();
});

2. Leverage Layouts for Shared Logic

// routes/(authenticated)/+layout.server.ts
export const load = async ({ locals }) => {
	const session = await locals.auth();
	// All child routes receive session
	return { sessionUser: session?.user };
};

3. Use Form Actions for Mutations

// Progressive enhancement - works without JS
export const actions = {
	create: async ({ request }) => {
		const data = await request.formData();
		// Handle mutation
		return { success: true };
	}
};

4. Type Everything

Use generated types from ./$types:

import type { PageServerLoad, Actions } from './$types';

export const load: PageServerLoad = async () => {
	/* ... */
};
export const actions: Actions = {
	/* ... */
};

5. Optimize Bundle Size

• Use code splitting for large dependencies

• Lazy load components that aren't immediately needed

• Preload critical routes

Related Documentation

• Authentication Flow - Auth.js integration

• Multi-Tenancy - Tenant context in routes

• System Overview - Overall architecture

• Developer Guide: Local Development - Running locally

---

Last updated: October 2025