# ocluf/justship architecture

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

- Interactive diagram: https://gitdiagram.com/ocluf/justship
- Repository: https://github.com/ocluf/justship

## Overview

##### Main Components
- UI components (Header, Form elements, Inputs, Buttons, etc.)
- Routes segregated into different concerns such as “(app)” for the main application UI, “(login)” for the authentication flows, and pages like privacy-policy, error handling, and sitemap.xml.
- Backend/Server: This includes server-side logic, APIs, and service integrations.
- Auth logic in src/lib/server/auth.ts
- Database interaction and models (user, signin, email token) in src/lib/server/database
- Email processing (templates and layouts) in src/lib/server/email
- API endpoints for social login (Google OAuth callbacks), email verification, and Stripe payment flows—found within the src/routes structure.
- Database: SQL migration scripts and Drizzle ORM integration are found in the drizzle directory. Migration scripts (0000, 0001, etc.) and snapshots ensure the database schema is maintained.
- External Services & Integrations:
- Email sending service via Postmark.
- Authentication with Lucia, including both social login (Google) and magic link.
- Payment processing through Stripe (endpoints exist under src/routes/stripe).
- Hosting/deployment on Vercel (with a vercel.json configuration).
- Database service using Turso.

##### Relationships and Interactions
- The Frontend interacts with the Backend through SvelteKit routes:
- The user interface defined in various Svelte components issues requests to API endpoints (e.g., for login, email verification, and handling Stripe events).
- The Backend handles authentication and authorization:
- Utilizes the Lucia library to authenticate users.
- Invokes email routines to send login links or verification messages.
- The Database layer is used for persisting user data, session tokens, and other state.
- Managed by Drizzle ORM with migration scripts provided under the drizzle folder.
- Communication to External Services happens as follows:
- When emails are sent (via the email module), the Postmark service API is triggered.
- During social login, Google Cloud’s OAuth endpoints are engaged.
- Payment events trigger interactions with Stripe’s API.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project isolates UI components, server logic, and database models into distinct folders.
- Serverless Architecture: Designed for quick deployment on Vercel, leveraging SvelteKit’s endpoints and serverless functions.
- Modular Component Architecture: All UI elements (buttons, forms, labels) are designed as reusable components.
- Clear API Boundaries: Different routes such as /login, /stripe, etc., have dedicated endpoints ensuring a clean separation between authentication, payment, and general app logic.

##### Relevant Technologies and Frameworks
- Svelte 5 & SvelteKit 2 – for building the reactive frontend and handling server routes.
- TailwindCSS and shadcn – for styling.
- Lucia – for authentication.
- Drizzle ORM paired with Turso – for database operations.
- Postmark – for email delivery.
- Stripe – for handling payments.
- Vercel – for serverless deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    UB("User Browser"):::external

    %% Frontend Subgraph
    subgraph "Frontend (Svelte UI)"
        FUI("UI Components"):::frontend
        FRA("Routes: (app)"):::frontend
        FRL("Routes: (login)"):::frontend
    end

    %% Backend / API Subgraph
    subgraph "Backend / API"
        AUTH("Authentication Module (Lucia)"):::backend
        DB("Database Module (Drizzle ORM)"):::backend
        MIG("Migration Scripts (Drizzle ORM)"):::backend
        EMAIL("Email Service (Postmark)"):::backend
        STRIPE("Payment Processing (Stripe)"):::backend
    end

    %% External Services Subgraph
    subgraph "External Services"
        GOOGLE("Google_OAuth"):::external
        POSTMARK("Postmark_API"):::external
        STRIPEAPI("Stripe_API"):::external
        TURSO("Turso_Database_Service"):::external
    end

    %% Deployment Node
    VERCEL("Deployment (Vercel)"):::deployment

    %% Connections from User to Frontend
    UB -->|"accesses"| FRA
    UB -->|"accesses"| FRL
    UB -->|"renders"| FUI

    %% Frontend to Backend Connections
    FRA -->|"calls"| AUTH
    FRL -->|"triggers"| AUTH
    FRA -->|"initiates"| STRIPE

    %% Backend Internal Connections
    AUTH -->|"queries"| DB
    DB -->|"managed_by"| MIG
    AUTH -->|"uses"| GOOGLE
    AUTH -->|"sends"| EMAIL
    EMAIL -->|"via"| POSTMARK
    STRIPE -->|"interacts_with"| STRIPEAPI
    DB -->|"stores_data"| TURSO

    %% Deployment Connection
    AUTH ---|"deployed_on"| VERCEL
    DB ---|"deployed_on"| VERCEL
    EMAIL ---|"deployed_on"| VERCEL
    STRIPE ---|"deployed_on"| VERCEL
    FRA ---|"deployed_on"| VERCEL
    FRL ---|"deployed_on"| VERCEL
    FUI ---|"deployed_on"| VERCEL

    %% Click Events for Component Mapping
    click FUI "https://github.com/ocluf/justship/tree/main/src/lib/components"
    click FRA "https://github.com/ocluf/justship/tree/main/src/routes/(app)"
    click FRL "https://github.com/ocluf/justship/tree/main/src/routes/(login)"
    click AUTH "https://github.com/ocluf/justship/blob/main/src/lib/server/auth.ts"
    click DB "https://github.com/ocluf/justship/tree/main/src/lib/server/database"
    click MIG "https://github.com/ocluf/justship/tree/main/drizzle"
    click EMAIL "https://github.com/ocluf/justship/tree/main/src/lib/server/email"
    click STRIPE "https://github.com/ocluf/justship/tree/main/src/routes/stripe"
    click VERCEL "https://github.com/ocluf/justship/blob/main/vercel.json"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef external fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef deployment fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
```
