SvelteKit Architecture

This document outlines the architecture of the project, including the components, their responsibilities, and how they interact with each other.

Table of Contents

1. Structure Overview
2. Folder Structure
3. Applied Architectural Principles

Structure Overview

.
├── src
│   ├── lib
│   │   ├── features
│   │   │   ├── features-1
│   │   │   │   ├── components
│   │   │   │   │   ├── ...
│   │   │   │   └── services
│   │   │   │       ├── __tests__/
│   │   │   │       │   └── test.ts
│   │   │   │       ├── daos.ts
│   │   │   │       ├── models.ts
│   │   │   │       └── queries.ts
│   │   │   ├── feature-2
│   │   │   │   ├── components
│   │   │   │   │   └── dashboard
│   │   │   │   │       ├── ...
│   │   │   │   └── services
│   │   │   │       ├── __tests__/
│   │   │   │       │   └── test.ts
│   │   │   │       ├── daos.ts
│   │   │   │       ├── models.ts
│   │   │   │       └── queries.ts
│   │   │   ├── shared/
│   │   │   │   ├── components/
│   │   │   │   │   ├── app-navbar.svelte
│   │   │   │   │   └── _shadcn
│   │   │   │   │       ├── ...
│   │   │   │   └── services/
│   │   │   │       ├── __tests__/
│   │   │   │       │   └── test.ts
│   │   │   │       ├── daos.ts
│   │   │   │       ├── models.ts
│   │   │   │       └── queries.ts
│   │   ├── config/
│   │   │   ├── ...
│   ├── routes
│   │   ├── +page.svelte
│   │   └── ...

Folder Structure

src/lib/

Contains all reusable logic, including components, services, utilities, and configurations. Organized as follows:

features/ – Feature-Specific Implementations

Implementations specific of UI components, services, hooks and more utilities to real application features (e.g. features/user, features/admin):

• components/ – Generic Components

  Contains UI components specific to the feature. This directory does not follow any specific pattern in order to allow for maximum flexibility to organize components as needed.

• services/ – Data Access Layer

  Each service follows the DAO + TanStack + Zod pattern:

  • __tests__/
    Unit tests for the service.

    • test.ts file is the entry point for the tests.

  • daos.ts
    Pure functions for direct data access (e.g., APIs, local databases).

    // lib/services/user/daos.ts
    import type { User } from "./models";
    
    export async function fetchUser(id: string): Promise<User> {
      const res = await fetch(`/api/users/${id}`);
      if (!res.ok) throw new Error("Failed to fetch user");
      return res.json();
    }
    
    export async function updateUser(id: string, data: User): Promise<User> {
      const res = await fetch(`/api/users/${id}`, {
        method: "PUT",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(data),
      });
      if (!res.ok) throw new Error("Failed to update user");
      return res.json();
    }
    

  • queries.ts
    TanStack Query hooks that wrap dao.ts with state and cache logic.

    // lib/services/user/queries.ts
    import { queryOptions, createMutation } from "@tanstack/svelte-query";
    import { fetchUser, updateUser } from "./dao";
    import { userModelSchema } from "./models";
    import type { UserModel } from "./models";
    
    export const userQueryKeys = {
      all: ["user"] as const,
      detail: (id: string) => [...userQueryKeys.all, "detail", id] as const,
    };
    
    export function useGetUserById(userId: string) {
      return queryOptions({
        queryKey: userQueryKeys.detail(userId),
        queryFn: () => fetchUser(userId),
      });
    }
    
    export function useUpdateUser() {
      return createMutation({
        mutationFn: async (user: UserModel) => {
          const parsed = userModelSchema.parse(user); // Validate input
          return updateUser(parsed.id, parsed);
        },
      });
    }
    

  • models.ts Defines data schemas and models using Zod for runtime validation and static type inference

    // lib/services/users/models.ts
    import { z } from "zod";
    
    export const userModelSchema = z.object({
      id: z.string(),
      name: z.string(),
      email: z.string().email(),
      createdAt: z.string(),
    });
    
    export type UserModel = z.infer<typeof UserModelSchema>;
    

features/shared/ – Shared implementations

Follows the same pattern as features/, but is intended for implementations that are shared across multiple features.

utils/ – Generic Utilities

Pure helper functions such as:

• Formatting
• Validation
• Conversions

config/ – Global Configurations

Defines aspects like:

• Base API URL
• Environment variables

src/routes/

Standard SvelteKit folder.

Responsible for:

• Rendering actual pages.
• Composing views using modules from lib/.

Applied Architectural Principles

Feature-Based Structure

Organize components and services per domain (e.g.: user/, admin/), not by type.

DAO Pattern

• dao.ts contains ONLY external data access logic.
• It DOES NOT process state, UI or business logic.

TanStack Query Integration

• queries.ts encapsulates hooks that uses dao.ts.
• Controls caching logic, onSuccess and onError callback management.