# lubomirgeorgiev/cloudflare-workers-nextjs-saas-template architecture

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

- Interactive diagram: https://gitdiagram.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template
- Repository: https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template

## Overview

##### Main Components
- Frontend UI & Routing Layer – Represented by the “src/app” folder, which is segmented into various functional parts such as authentication ((auth) subdirectory), dashboard (marketplace, billing, settings, etc.), legal, and marketing pages. This component uses Next.js (server components, React components) along with modern UI technologies (Tailwind CSS, shadcn/ui).
- Backend API & Actions – API endpoints and action files are distributed in “src/app/api” and “src/actions”. This includes session handling, authentication actions, and billing operations.
- Authentication Module – Look at the “src/app/(auth)” and associated client and server action files. This module integrates several authentication strategies (email/password, passkey, OAuth through Google) and manages workflows like password resets and email verification.
- Database Layer – Found under “src/db” and “drizzle.config.ts”, this component handles migrations, schema definitions, and the communication with the Cloudflare D1 database in production (and SQLite for local development) with a type-safe interface.
- Email Service – Under “src/react-email”, the project has built-in email templates for actions like password reset and email verification. It interfaces with external providers like Resend or Brevo.
- Payment/Billing Component – Within “src/app/(dashboard)/dashboard/billing” and related scripts, the application integrates credit billing functionality using Stripe along with client components for payment forms and transaction histories.
- External Integrations & Edge Services – This includes the Cloudflare Workers deployment (guided by “wrangler.jsonc” and deployment scripts in “.github/workflows/”) and session storage using Cloudflare KV, as well as rate limiting and other security measures.
- Utility Libraries & Services – Modules for handling shared business logic (in “src/lib”, “src/utils”, “src/schemas”, “src/hooks”) which underpin authentication, session management, and API interactions.

##### Relationships and Interactions
- The user interacts with the Frontend UI, which routes them to different parts of the application (auth, dashboard, marketing, settings).
- When a user performs an action (e.g., sign-in, sign-up, purchase, or email verification), the frontend issues requests to the backend API endpoints.
- The Backend API coordinates with multiple services/components: it authenticates requests, performs business logic (e.g., billing, session management), interacts with the database for persistent storage (using Drizzle and migrations), and handles external integrations (e.g., contacting the email service or Stripe).
- Cloudflare Workers host the entire application deployment, ensuring global edge delivery, zero cold starts, and handling tasks like KV session storage, API routing, and rate limiting.

##### Architectural Patterns & Design Principles
- Separation of Concerns – The file structure clearly segregates responsibilities (UI components, API actions, authentication workflows, database interactions).
- Modular Architecture – Components such as authentication, billing, and email services are self-contained, making extensions or modifications straightforward.
- Edge-first Deployment – Leveraging Cloudflare Workers and KV storage ensures low latency and high scalability.
- Type-Safety and Validation – The use of TypeScript, Zod schemas, and Drizzle’s type-safe queries ensures that data and logic are robustly validated.
- CI/CD Integration – Automated deployments via GitHub Actions (as evident from the GitHub workflows) enforce a strong DevOps pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Section
    U("User"):::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE("Frontend (Next.js UI)"):::internal
        Auth("Authentication Module"):::internal
    end

    %% Backend Services
    subgraph "Backend Services"
        API("API & Business Logic"):::internal
        DB("Database (D1/SQLite)"):::internal
        Email("Email Service (React Email)"):::internal
        Billing("Billing Module (Stripe)"):::internal
        External("Cloudflare & External Services"):::external
        Utils("Utility Libraries"):::internal
    end

    %% Interactions
    U -->|"HTTPRequest"| FE
    FE -->|"NavigateToAuth"| Auth
    FE -->|"APICall"| API
    Auth -->|"AuthRequest"| API
    API -->|"DBQuery"| DB
    API -->|"SendEmail"| Email
    API -->|"BillingOps"| Billing
    API -->|"ExternalCall"| External
    API -->|"UtilityCall"| Utils

    %% Click Events
    click FE "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/app"
    click API "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/app/api"
    click API "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/actions"
    click Auth "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/app/(auth)"
    click DB "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/db"
    click DB "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/blob/main/drizzle.config.ts"
    click Email "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/react-email"
    click Billing "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/app/(dashboard)/dashboard/billing"
    click External "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/blob/main/wrangler.jsonc"
    click External "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/.github/workflows"
    click Utils "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/lib"
    click Utils "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/utils"
    click Utils "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/schemas"
    click Utils "https://github.com/lubomirgeorgiev/cloudflare-workers-nextjs-saas-template/tree/main/src/hooks"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#008000,stroke-width:2px;
```
