# imperatrona/svelte-auth architecture

> Architecture diagram of the GitHub repository imperatrona/svelte-auth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imperatrona/svelte-auth
- Repository: https://github.com/imperatrona/svelte-auth

## Overview

##### Project Type and Purpose
- This is a full-stack SvelteKit application that provides an authentication template.
- It uses Lucia for session management and authentication, Drizzle as the ORM layer on top of a SQLite database, and integrates with external services (OAuth via GitHub and email for password reset/verification).

##### File Structure Analysis
- Top level:
- drizzle/ & drizzle.config.ts – database migrations and configuration for Drizzle ORM
- src/ – application source (both client and server code)
- static/ – CSS and other static assets
- svelte.config.js, vite.config.ts – build and bundler configs
- src/lib: reusable modules
- components/forms – Svelte UI components (Button, Input, InputError)
- server – server-side code:
– auth.ts: Lucia setup
– db.ts: Drizzle ORM client
– mail.ts: email dispatch logic
– schema.ts: table definitions
- script/migrate.ts – one-off migration runner
- utils & validation – helper functions and validation logic
- src/routes: page routes and API endpoints
- (auth)/(sign)/signin & signup – form UI and server handlers
- (auth)/reset-password, (auth)/verify – email workflows
- profile and profile/edit – protected user pages
- hooks.server.ts – SvelteKit hooks to attach sessions to requests

##### Key Components
a. Client (Browser)
- SvelteKit-rendered pages and Svelte components in the client bundle
- Static assets (styles.css)
b. Web Server (Node.js + SvelteKit)
- SSR endpoints in +page.server.ts and +server.ts
- hooks.server.ts for session initialization/validation
- API routes for sign-in, sign-up, reset, verify, profile CRUD
c. Auth Service (Lucia)
- Session store & user management plugged into SvelteKit hooks
d. ORM Layer (Drizzle)
- db.ts exposing query builder and migration scripts
- Migrations under drizzle/ folder
e. Database (SQLite)
- Local .sqlite file
f. External Services
- GitHub OAuth (signin/github endpoint)
- SMTP/email provider (mail.ts sending verification/reset links)

##### Relationships and Data Flow
1. Browser requests HTML/JS from SvelteKit server via Vite dev server or built bundle.
2. User submits sign-in/up/reset forms → POST to server endpoints.
3. Server handlers invoke Lucia (auth.ts) and Drizzle (db.ts) to read/write user and session records in SQLite.
4. For OAuth: server redirects to GitHub, receives callback, then creates/validates user session.
5. For email flows: server uses mail.ts to call external SMTP API.
6. Authenticated requests to protected routes hit hooks.server.ts which verifies session with Lucia before rendering.

##### Architectural Patterns & Design Principles
- Full-stack SSR with client hydration (SvelteKit)
- Layered separation:
- UI Components → Routes → Server handlers → Auth & ORM → Database
- Modularization: reusable components in src/lib/components, domain logic in server folder
- Configuration as code: drizzle.config.ts, vite.config.ts, svelte.config.js

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Browser"]:::client
    UIComponents["UI Components\n(src/lib/components/forms)"]:::client
    StaticAssets["Static Assets\n(styles.css)"]:::client

    %% Server Layer
    subgraph "Web Server (Node.js + SvelteKit)"
        Routes["SvelteKit Routes\n(src/routes)"]:::server
        Hooks["Session Hook\nhooks.server.ts"]:::server
        AuthSvc["Lucia Auth Service\nsrc/lib/server/auth.ts"]:::server
        ORM["Drizzle ORM Client\nsrc/lib/server/db.ts"]:::server
        Schema["Drizzle Schema Definitions\nsrc/lib/server/schema.ts"]:::server
        Migrations["Database Migrations\n(drizzle/)"]:::server
        Mail["Email Dispatch Service\nsrc/lib/server/mail.ts"]:::server
        Utils["Utils & Validation\nsrc/lib/utils & src/lib/validation"]:::server
        Script["Migration Runner Script\nsrc/lib/script/migrate.ts"]:::server

        subgraph "Auth Routes"
            SignInComp["Sign-in Page Component\n+page.svelte"]:::server
            SignInHandler["Sign-in Handler\n+page.server.ts"]:::server
            GitHubOAuth["GitHub OAuth Endpoint\n+server.ts"]:::server
            SignUpComp["Sign-up Page Component\n+page.svelte"]:::server
            SignUpHandler["Sign-up Handler\n+page.server.ts"]:::server
            ResetComp["Password Reset Page Component\n+page.svelte"]:::server
            ResetHandler["Password Reset Handler\n+page.server.ts"]:::server
            VerifyError["Email Verification Error View\n+error.svelte"]:::server
            VerifyCallback["Email Verification Callback Handler\n[token]/+server.ts"]:::server
        end

        subgraph "Protected Routes"
            ProfileComp["Profile Page Component\n+page.svelte"]:::server
            ProfileHandler["Profile Handler\n+page.server.ts"]:::server
            EditComp["Profile Edit Component\n+page.svelte"]:::server
            EditHandler["Profile Edit Handler\n+page.server.ts"]:::server
        end
    end

    %% Database Layer
    DB["SQLite Database\n(.sqlite file)"]:::db

    %% External Services
    OAuthService["GitHub OAuth\nExternal Service"]:::external
    SMTPService["SMTP Email Provider"]:::external

    %% Connections
    Client -->|"HTTP GET HTML/JS"| Routes
    Client -->|"GET CSS"| StaticAssets
    Routes --> Hooks
    Hooks --> AuthSvc
    AuthSvc --> ORM
    ORM --> Schema
    ORM --> DB
    Migrations --> DB
    Routes --> Mail
    Mail --> SMTPService
    Routes --> OAuthService

    %% Route Component Data Flow
    SignInComp -->|"/auth/signin POST"| SignInHandler
    SignUpComp -->|"/auth/signup POST"| SignUpHandler
    ResetComp -->|"/auth/reset-password POST"| ResetHandler
    VerifyCallback -->|"/auth/verify callback"| VerifyCallback
    ProfileComp -->|"Auth Check"| ProfileHandler
    EditComp -->|"Auth Check"| EditHandler
    GitHubOAuth -->|"OAuth Redirect/Callback"| Routes

    %% Click Events
    click UIComponents "https://github.com/imperatrona/svelte-auth/tree/main/src/lib/components/forms"
    click StaticAssets "https://github.com/imperatrona/svelte-auth/blob/main/static/styles.css"
    click Routes "https://github.com/imperatrona/svelte-auth/tree/main/src/routes"
    click SignInHandler "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/(sign)/signin/+page.server.ts"
    click SignInComp "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/(sign)/signin/+page.svelte"
    click GitHubOAuth "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/(sign)/signin/github/+server.ts"
    click SignUpHandler "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/(sign)/signup/+page.server.ts"
    click SignUpComp "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/(sign)/signup/+page.svelte"
    click ResetHandler "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/reset-password/+page.server.ts"
    click ResetComp "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/reset-password/+page.svelte"
    click VerifyError "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/verify/+error.svelte"
    click VerifyCallback "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/(auth)/verify/[token]/+server.ts"
    click ProfileHandler "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/profile/+page.server.ts"
    click ProfileComp "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/profile/+page.svelte"
    click EditHandler "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/profile/edit/+page.server.ts"
    click EditComp "https://github.com/imperatrona/svelte-auth/blob/main/src/routes/profile/edit/+page.svelte"
    click Hooks "https://github.com/imperatrona/svelte-auth/blob/main/src/hooks.server.ts"
    click AuthSvc "https://github.com/imperatrona/svelte-auth/blob/main/src/lib/server/auth.ts"
    click ORM "https://github.com/imperatrona/svelte-auth/blob/main/src/lib/server/db.ts"
    click Schema "https://github.com/imperatrona/svelte-auth/blob/main/src/lib/server/schema.ts"
    click Migrations "https://github.com/imperatrona/svelte-auth/tree/main/drizzle/"
    click Mail "https://github.com/imperatrona/svelte-auth/blob/main/src/lib/server/mail.ts"
    click Script "https://github.com/imperatrona/svelte-auth/blob/main/src/lib/script/migrate.ts"
    click Utils "https://github.com/imperatrona/svelte-auth/tree/main/src/lib/validation"
    click Utils "https://github.com/imperatrona/svelte-auth/tree/main/src/lib/utils"

    %% Styles
    classDef client fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef server fill:#a2c8f5,stroke:#333,stroke-width:1px
    classDef db fill:#f5c38f,stroke:#333,stroke-width:1px
    classDef external fill:#e5a2f5,stroke:#333,stroke-width:1px
```
