# daveyplate/better-auth-nextjs-starter architecture

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

- Interactive diagram: https://gitdiagram.com/daveyplate/better-auth-nextjs-starter
- Repository: https://github.com/daveyplate/better-auth-nextjs-starter

## Overview

##### Main components
a. Frontend (Next.js App Router)
b. Backend API (Next.js serverless functions under app/api)
c. Authentication service (Better Auth)
d. Database layer (PostgreSQL via Drizzle ORM)
e. Client-side state & data fetching (TanStack Query)
f. UI Library & Styles (shadcn/ui, TailwindCSS)
g. External services & tooling (Better-Auth CLI, migrations, Vercel)

##### Relationships and data flows
- User’s browser loads React pages from the Next.js frontend.
- On page load or user actions, the frontend calls internal API routes (app/api/auth/[...all]/route.ts).
- API routes use lib/auth and lib/auth-client to communicate with Better Auth (via REST or SDK) for sign-in, token validation, and session management.
- Authenticated API handlers then use Drizzle ORM (database/db.ts + schema.ts) to read/write user data in PostgreSQL.
- Client code uses TanStack Query hooks (hooks/auth-hooks.ts) to fetch and cache server data.
- UI components (components/ui/* and components/*) render based on data and auth state.
- Middleware.ts enforces route protection & redirects on the server.

##### Architectural patterns and design principles
- Next.js App Router – server/client boundary, automatic code splitting, server-side rendering (SSR) or static generation (SSG).
- MVC-style separation: API routes (Controller), Drizzle ORM + database (Model), React pages + components (View).
- Single codebase monorepo orchestrated by Turborepo (turbo.json).
- Environment-driven configuration (.env, drizzle.config.ts, next.config.ts).
- Hooks and provider pattern for cross-cutting concerns (auth state, themes).

##### Key technologies and their roles
- Next.js: Routing, SSR/SSG, API routes
- Better Auth & Better-Auth UI: Authentication backend & prebuilt React UI
- Drizzle ORM + drizzle-kit: Schema generation, migrations, type-safe DB access
- PostgreSQL: Relational data store
- TanStack Query: Client-side data fetching & caching
- shadcn/ui + TailwindCSS: Component library + styling
- Biome: Linting/formatting
- Turborepo: Build & workspace management

##### Detail level
- Every major folder/group (app, components, lib, database, hooks).
- Middleware or provider that impacts global behavior (e.g., auth redirects).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    Browser["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend (Next.js App Router)"
        FEPage["app/page.tsx"]:::frontend
        FELayout["app/layout.tsx"]:::frontend
        FEProviders["app/providers.tsx"]:::frontend
        FEAuthPage["app/auth/[pathname]/page.tsx"]:::frontend
        FEAuthView["app/auth/[pathname]/view.tsx"]:::frontend
        UIlib["components/ui/"]:::frontend
        GenComp["components/"]:::frontend
        Hooks["hooks/auth-hooks.ts"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API"
        API["app/api/auth/[...all]/route.ts"]:::backend
        Middleware["middleware.ts"]:::backend
        AuthClient["lib/auth-client.ts"]:::backend
        AuthLib["lib/auth.ts"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        DBConfig["drizzle.config.ts"]:::data
        DBConn["database/db.ts"]:::data
        DBSchema["database/schema.ts"]:::data
        AuthSchema["auth-schema.ts"]:::data
    end

    %% External Services
    subgraph "External Services"
        BetterAuth["Better Auth Service"]:::external
        Postgres["PostgreSQL"]:::external
    end

    %% Tooling & Deployment
    subgraph "Tooling & Deployment"
        CLI["Better-Auth CLI"]:::tooling
        Migrations["drizzle-kit migrations"]:::tooling
        Vercel["Vercel Deployment"]:::tooling
    end

    %% Connections
    Browser -->|"HTTP (fetch)"| FEPage
    FEPage -->|"uses Providers"| FEProviders
    FEProviders --> UIlib
    UIlib --> GenComp
    GenComp --> Hooks
    FEPage -->|"useQuery"| Hooks
    Hooks -->|"fetch /api"| API
    Browser --> Middleware
    Middleware --> API
    API --> AuthClient
    API --> AuthLib
    AuthClient --> BetterAuth
    AuthLib --> BetterAuth
    API -->|"Drizzle ORM"| DBConn
    DBConn --> DBSchema
    DBConn --> Postgres

    %% Click Events
    click FEPage "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/app/page.tsx"
    click FELayout "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/app/layout.tsx"
    click FEProviders "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/app/providers.tsx"
    click FEAuthPage "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/app/auth/[pathname]/page.tsx"
    click FEAuthView "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/app/auth/[pathname]/view.tsx"
    click UIlib "https://github.com/daveyplate/better-auth-nextjs-starter/tree/main/components/ui/"
    click GenComp "https://github.com/daveyplate/better-auth-nextjs-starter/tree/main/components/"
    click Hooks "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/hooks/auth-hooks.ts"
    click API "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/app/api/auth/[...all]/route.ts"
    click Middleware "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/middleware.ts"
    click AuthClient "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/lib/auth-client.ts"
    click AuthLib "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/lib/auth.ts"
    click DBConfig "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/drizzle.config.ts"
    click DBConn "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/database/db.ts"
    click DBSchema "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/database/schema.ts"
    click AuthSchema "https://github.com/daveyplate/better-auth-nextjs-starter/blob/main/auth-schema.ts"

    %% Styles
    classDef frontend fill:#E0F2FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E6FFED,stroke:#028A0F,color:#028A0F
    classDef data fill:#FFF4E5,stroke:#E3790B,color:#E3790B
    classDef external fill:#F0F0F0,stroke:#888888,color:#888888
    classDef tooling fill:#F9F5FF,stroke:#8A2BE2,color:#8A2BE2
```
