# nextjs/saas-starter architecture

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

- Interactive diagram: https://gitdiagram.com/nextjs/saas-starter
- Repository: https://github.com/nextjs/saas-starter

## Overview

##### Main Components
- Frontend Client: Outline the user-facing pages. This includes:
- The marketing landing page, pricing page, and animated terminal element.
- The authentication pages under the “app/(login)” directory (sign-in and sign-up flows).
- The authenticated dashboard area under “app/(dashboard)” with its nested pages (activity, general, security, team invites, pricing, etc.).
- Shared UI components found in “components/ui”.
- API Routes: Represent the endpoints under “app/api” that include:
- Stripe payment processing (checkout and webhook endpoints).
- Other server-side logic that might be handling CRUD operations and other business logic.
- Backend/Server-Side Logic:
- The “lib” folder that contains modules for authentication (JWT, session management), database operations (queries, schema, migrations, seeding) and payments (Stripe interactions).
- Global middleware (“middleware.ts” and files in “lib/auth”) ensuring routes are protected and session validation is done.
- Database & ORM:
- The Postgres database supported by the Drizzle ORM. Use the “lib/db” folder which contains migrations, seed scripts, queries, and schema definitions.
- External Services:
- Stripe (for payments and webhook handling).
- Vercel deployment considerations as described in the README.

##### Relationships and Interactions
- Frontend to API: Indicate that the Next.js pages (dashboard, pricing, sign-in/up) call server actions or API endpoints for authentication, data fetching, or payment processing.
- API and Business Logic: Show how API routes within “app/api” invoke functions from the “lib” folder (e.g., lib/payments or lib/db) to handle business logic.

##### Architectural Patterns and Design Principles
- Modular Separation: Highlight that the project separates concerns by isolating pages (views), API routes, business logic (in lib), and UI components (in components/ui).
- Server Actions and Middleware: Emphasize that Next.js server components and middleware are used to secure and manage state on the backend.
- ORM and Database Migrations: Note that Drizzle configuration and migrations ensure the database’s schema is managed predictably.
- Extensibility: Illustrate integration points for payments, authentication, and activity logging allowing future extensions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    Browser["User Browser"]:::user

    %% Frontend Subgraph
    subgraph "Frontend (Next.js)"
        Layout["Landing (app/layout.tsx)"]:::frontend
        NotFound["NotFound (app/not-found.tsx)"]:::frontend
        Login["Login (app/(login)/login.tsx)"]:::frontend
        SignIn["Sign In (app/(login)/sign-in/page.tsx)"]:::frontend
        SignUp["Sign Up (app/(login)/sign-up/page.tsx)"]:::frontend
        DashboardMain["Dashboard Main (app/(dashboard)/dashboard/page.tsx)"]:::frontend
        DashboardActivity["Dashboard Activity (app/(dashboard)/dashboard/activity/page.tsx)"]:::frontend
        DashboardGeneral["Dashboard General (app/(dashboard)/dashboard/general/page.tsx)"]:::frontend
        DashboardSecurity["Dashboard Security (app/(dashboard)/dashboard/security/page.tsx)"]:::frontend
        DashboardPricing["Dashboard Pricing (app/(dashboard)/pricing/page.tsx)"]:::frontend
        DashboardInvite["Dashboard Invite (app/(dashboard)/dashboard/invite-team.tsx)"]:::frontend
        DashboardSettings["Dashboard Settings (app/(dashboard)/dashboard/settings.tsx)"]:::frontend
        DashboardTerminal["Dashboard Terminal (app/(dashboard)/terminal.tsx)"]:::frontend
        UIComponents["UI Components (components/ui)"]:::frontend
    end

    %% API Endpoints Subgraph
    subgraph "API Endpoints"
        StripeCheckout["Stripe Checkout (app/api/stripe/checkout/route.ts)"]:::api
        StripeWebhook["Stripe Webhook (app/api/stripe/webhook/route.ts)"]:::api
    end

    %% Backend/Server-Side Logic Subgraph
    subgraph "Backend Logic"
        subgraph "Authentication & Middleware"
            AuthIndex["Auth Index (lib/auth/index.tsx)"]:::backend
            AuthMiddleware["Auth Middleware (lib/auth/middleware.ts)"]:::backend
            Session["Session (lib/auth/session.ts)"]:::backend
            GlobalMiddleware["Global Middleware (middleware.ts)"]:::backend
        end
        subgraph "Payments Module"
            PaymentsActions["Payments Actions (lib/payments/actions.ts)"]:::backend
            StripeIntegration["Stripe Integration (lib/payments/stripe.ts)"]:::backend
        end
    end

    %% Database & ORM Subgraph
    subgraph "Database Layer (Drizzle ORM)"
        DBDrizzle["DB Drizzle (lib/db/drizzle.ts)"]:::database
        DBSchema["DB Schema (lib/db/schema.ts)"]:::database
        DBQueries["DB Queries (lib/db/queries.ts)"]:::database
        DBSeed["DB Seed (lib/db/seed.ts)"]:::database
        DBSetup["DB Setup (lib/db/setup.ts)"]:::database
        DBMigrations["DB Migrations (lib/db/migrations)"]:::database
        DBMigrationMeta["Migration Meta (lib/db/migrations/meta)"]:::database
    end

    %% External Services Subgraph
    subgraph "External Services"
        StripeService["Stripe Service"]:::external
    end

    %% Connections - Browser to Frontend
    Browser -->|"loads"| Layout
    Browser -->|"loads"| Login
    Browser -->|"loads"| SignIn
    Browser -->|"loads"| SignUp
    Browser -->|"loads"| DashboardMain

    %% Frontend to API Endpoints
    Layout -->|"calls"| StripeCheckout
    Login -->|"triggers"| AuthIndex
    SignIn -->|"triggers"| AuthIndex
    SignUp -->|"triggers"| AuthIndex
    DashboardMain -->|"fetches"| DBDrizzle
    DashboardActivity -->|"queries"| DBQueries
    DashboardSecurity -->|"secures"| AuthMiddleware
    DashboardPricing -->|"initiates"| PaymentsActions
    UIComponents ---|"shared by"| Layout
    UIComponents --- UIComponents

    %% API Endpoints to Backend Logic
    StripeCheckout -->|"processes"| PaymentsActions
    StripeWebhook -->|"relays"| PaymentsActions
    StripeCheckout -->|"protected_by"| GlobalMiddleware
    AuthIndex -->|"utilizes"| Session
    AuthMiddleware -->|"reinforces"| GlobalMiddleware

    %% Payments Module to External Services
    PaymentsActions -->|"integrates"| StripeIntegration
    StripeIntegration -->|"communicates_with"| StripeService

    %% Database interactions
    DBQueries -->|"runs_on"| DBDrizzle
    DBDrizzle -->|"defines"| DBSchema

    %% Click Events for Frontend Components
    click Layout "https://github.com/nextjs/saas-starter/blob/main/app/layout.tsx"
    click NotFound "https://github.com/nextjs/saas-starter/blob/main/app/not-found.tsx"
    click Login "https://github.com/nextjs/saas-starter/blob/main/app/(login)/login.tsx"
    click SignIn "https://github.com/nextjs/saas-starter/blob/main/app/(login)/sign-in/page.tsx"
    click SignUp "https://github.com/nextjs/saas-starter/blob/main/app/(login)/sign-up/page.tsx"
    click DashboardMain "https://github.com/nextjs/saas-starter/blob/main/app/(dashboard)/dashboard/page.tsx"
    click DashboardActivity "https://github.com/nextjs/saas-starter/blob/main/app/(dashboard)/dashboard/activity/page.tsx"
    click DashboardGeneral "https://github.com/nextjs/saas-starter/blob/main/app/(dashboard)/dashboard/general/page.tsx"
    click DashboardSecurity "https://github.com/nextjs/saas-starter/blob/main/app/(dashboard)/dashboard/security/page.tsx"
    click DashboardPricing "https://github.com/nextjs/saas-starter/blob/main/app/(dashboard)/pricing/page.tsx"
    click DashboardInvite "https://github.com/nextjs/saas-starter/blob/main/app/(dashboard)/dashboard/invite-team.tsx"
    click DashboardSettings "https://github.com/nextjs/saas-starter/blob/main/app/(dashboard)/dashboard/settings.tsx"
    click DashboardTerminal "https://github.com/nextjs/saas-starter/blob/main/app/(dashboard)/terminal.tsx"
    click UIComponents "https://github.com/nextjs/saas-starter/tree/main/components/ui"

    %% Click Events for API Routes
    click StripeCheckout "https://github.com/nextjs/saas-starter/blob/main/app/api/stripe/checkout/route.ts"
    click StripeWebhook "https://github.com/nextjs/saas-starter/blob/main/app/api/stripe/webhook/route.ts"

    %% Click Events for Backend Authentication & Middleware
    click AuthIndex "https://github.com/nextjs/saas-starter/blob/main/lib/auth/index.tsx"
    click AuthMiddleware "https://github.com/nextjs/saas-starter/blob/main/lib/auth/middleware.ts"
    click Session "https://github.com/nextjs/saas-starter/blob/main/lib/auth/session.ts"
    click GlobalMiddleware "https://github.com/nextjs/saas-starter/blob/main/middleware.ts"

    %% Click Events for Payments Module
    click PaymentsActions "https://github.com/nextjs/saas-starter/blob/main/lib/payments/actions.ts"
    click StripeIntegration "https://github.com/nextjs/saas-starter/blob/main/lib/payments/stripe.ts"

    %% Click Events for Database Components
    click DBDrizzle "https://github.com/nextjs/saas-starter/blob/main/lib/db/drizzle.ts"
    click DBSchema "https://github.com/nextjs/saas-starter/blob/main/lib/db/schema.ts"
    click DBQueries "https://github.com/nextjs/saas-starter/blob/main/lib/db/queries.ts"
    click DBSeed "https://github.com/nextjs/saas-starter/blob/main/lib/db/seed.ts"
    click DBSetup "https://github.com/nextjs/saas-starter/blob/main/lib/db/setup.ts"
    click DBMigrations "https://github.com/nextjs/saas-starter/tree/main/lib/db/migrations"
    click DBMigrationMeta "https://github.com/nextjs/saas-starter/tree/main/lib/db/migrations/meta"

    %% Styles
    classDef user fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef frontend fill:#bbdefb,stroke:#333,stroke-width:2px;
    classDef api fill:#c5e1a5,stroke:#333,stroke-width:2px;
    classDef backend fill:#a5d6a7,stroke:#333,stroke-width:2px;
    classDef database fill:#ffe082,stroke:#333,stroke-width:2px;
    classDef external fill:#ef9a9a,stroke:#333,stroke-width:2px;
```
