System Architecture Overview

Introduction

The Refresh App Web is a modern, multi-tenant SaaS application built with SvelteKit 2 and Svelte 5, deployed on Cloudflare's global edge network. The application provides a comprehensive platform for workforce analytics, integrations, and risk detection.

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Cloudflare Edge Network                  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │         Cloudflare Workers (SvelteKit App)             │ │
│  │  • SSR & Client-Side Rendering                         │ │
│  │  • API Routes                                          │ │
│  │  • Authentication (Auth.js)                            │ │
│  │  • JWT Generation                                      │ │
│  └────────────┬───────────────────────┬───────────────────┘ │
└───────────────┼───────────────────────┼─────────────────────┘
                │                       │
                ├───────────────────────┼─────────────────┐
                │                       │                 │
       ┌────────▼───────-─┐    ┌────────▼─────┐  ┌───────▼────────┐
       │   Neon Postgres  │    │  Cloudflare  │  │  External APIs │
       │  (Multi-Region)  │    │      R2      │  │  • Google      │
       │   • Primary (NA) │    │   (Storage)  │  │  • Microsoft   │
       │   • Read Replicas│    │              │  │  • Stripe      │
       │   • RLS with JWT │    │              │  │  • Linear      │
       └──────────────────┘    └──────────────┘  └────────────────┘

Core Components

1. Frontend Layer

Technology Stack:

• SvelteKit 2: Meta-framework for server-side rendering and routing

• Svelte 5: Reactive UI framework with runes

• Tailwind CSS 4: Utility-first CSS framework

• Bits UI: Accessible component library

• Chart.js: Data visualization

Key Features:

• Server-side rendering (SSR) at the edge

• File-based routing with layouts

• Type-safe forms with Superforms

• Real-time reactivity with Svelte runes

• Responsive design with dark mode support

2. Backend Layer

Runtime:

• Cloudflare Workers: V8 isolates running at the edge

• Node.js Compatibility: Using nodejs_compat flag

• SvelteKit Adapter: @sveltejs/adapter-cloudflare

Key Features:

• API routes for internal operations

• Server-side data fetching with load functions

• Edge middleware for authentication and security

• Session management with cookies

3. Database Layer

Primary Database:

• Neon Postgres: Serverless Postgres with multi-region support

• Drizzle ORM: Type-safe SQL query builder

• Row-Level Security (RLS): Tenant isolation using JWT claims

Architecture:

• Primary write region: North America (us-east-1)

• Read replicas in multiple regions for low latency

• Logical replication from staging to development

• Connection pooling with Neon's serverless driver

4. Authentication & Authorization

Authentication Provider:

• Auth.js (formerly NextAuth): OAuth integration

• Supported Providers: Google, Microsoft Entra ID

• Drizzle Adapter: Session persistence in Neon

Authorization:

• Multi-tenant architecture with tenant/group roles

• Row-Level Security (RLS) in Postgres using JWT claims

• Custom JWT generation for Neon with JWKS endpoint

• Session caching for performance

5. Storage Layer

Cloudflare R2:

• Object storage for images and files

• S3-compatible API

• Integrated with the application via R2 bindings

• Presigned URLs for secure uploads/downloads

Design Principles

1. Edge-First Architecture

The application runs entirely on Cloudflare's edge network, ensuring:

• Low latency globally (sub-50ms response times)

• High availability with automatic failover

• Scalability without server management

• Cost efficiency (pay-per-request model)

2. Multi-Tenancy

Tenant isolation is achieved through:

• Application-level: Tenant context in session

• Database-level: RLS policies using JWT claims

• Storage-level: Tenant-prefixed object keys

3. Type Safety

End-to-end type safety with:

• TypeScript for all code

• Drizzle ORM for type-safe database queries

• Zod schemas for runtime validation

• SvelteKit's type inference for routes

4. Security-First

• HTTPS enforcement (HTTP → HTTPS redirect)

• Strict security headers (CSP, HSTS, X-Frame-Options)

• JWT-based authentication with RS256 signing

• JWKS endpoint for public key distribution

• Environment variable isolation per environment

5. Performance Optimization

• Server-side rendering at the edge

• Session caching to reduce database queries

• Optimized bundle splitting

• Database connection pooling

• Lazy loading of components

Data Flow

Request Flow

1. Client Request → Cloudflare edge network

2. Security Handler → HTTP → HTTPS redirect, security headers

3. Auth Handler → Session validation, JWT refresh

4. Tenant Context Handler → Set active tenant from cookie

5. Route Handler → Execute SvelteKit route

6. Database Query → Neon Postgres with JWT (RLS enforcement)

7. Response → Rendered HTML or JSON

Authentication Flow

1. User initiates OAuth login (Google/Microsoft)

2. OAuth callback validates user

3. User record created/updated in database

4. Session created with tenant/group memberships

5. Neon JWT generated with user ID and tenant ID

6. Session cached in memory (1 hour TTL)

7. JWT refreshed when expired or tenant changes

Technology Stack

Frontend

• SvelteKit 2.25.1

• Svelte 5.0

• TypeScript 5.0

• Tailwind CSS 4.1

• Vite 6.3

Backend

• Cloudflare Workers

• Node.js 22+

• Drizzle ORM 0.44

• Auth.js (SvelteKit) 1.10

• Zod 3.24

Database

• Neon Postgres

• Drizzle Kit (migrations)

Infrastructure

• Cloudflare Pages/Workers

• Cloudflare R2

• AWS SSM (secrets management)

• GitHub Actions (CI/CD)

External Services

• Google Workspace APIs

• Microsoft Graph API

• Stripe (billing)

• Linear (project management)

• PostHog (analytics)

Security

Multi-layered security model. See Security Architecture for details.

Scalability Considerations

Horizontal Scaling

• Cloudflare Workers auto-scale based on demand

• No server provisioning required

• Global distribution across 300+ data centers

Database Scaling

• Neon autoscaling for compute

• Read replicas for geographic distribution

• Connection pooling for efficient resource usage

Caching Strategy

• Session cache (in-memory, 1 hour TTL)

• Edge caching for static assets

• Database query results cached when appropriate

Monitoring & Observability

Metrics

• Cloudflare Analytics for request metrics

• PostHog for user analytics

• Error tracking with PostHog

Logging

• Cloudflare Workers logs

• Real-time log streaming with wrangler tail

• Centralized error reporting

Deployment

Four environments with auto-promotion: PR Sandbox → Development → Staging → Production. See Cloudflare Deployment and Operations Deployment Guide.

Related Documentation

• SvelteKit Architecture

• Authentication Flow

• Database Architecture

• Cloudflare Deployment

• Multi-Tenancy

• Security

---

Last updated: October 2025