# moltivie/the-t3-stack architecture

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

- Interactive diagram: https://gitdiagram.com/moltivie/the-t3-stack
- Repository: https://github.com/moltivie/the-t3-stack

## Overview

##### Project type and purpose
- This is a full-stack Next.js (T3) CRUD web application.
- Users land on a public list/detail view (read-only). Authenticated users with role >1 can create/update/delete.

##### File structure
- Top-level frameworks & config: next.config.mjs, tsconfig.json, Tailwind, ESLint, Prettier, Prisma schema.
- Frontend UI under src/pages: React pages, dynamic routes, Tailwind CSS in src/styles.
- API layer under src/pages/api: NextAuth routes under /auth, TRPC endpoint under /trpc, miscellaneous example/restricted endpoints.
- Backend business logic under src/server:
- common/ – shared helpers (e.g. auth session)
- db/ – Prisma client setup
- trpc/ – context builder and routers for auth, users, moderator, and main app router.
- Utilities in src/utils and environment schemas in src/env.

##### Extract architecture insights from the README
- NextAuth + GitHub OAuth for authentication.
- tRPC for type-safe frontend↔backend RPC.
- Prisma ORM backed by PlanetScale (MySQL) for persistence.
- Mock data service (mockAPI) used for initial example data.
- Role-based access control enforced in router resolvers.

##### Main components and their interactions
a. Client (Browser)
- Renders Next.js pages (React)
- Calls tRPC client hooks for data operations
- Redirects for OAuth login via NextAuth
b. Next.js Server
- Serves pages (SSR/SSG/CSR)
- Hosts API routes:
– /api/auth/[...nextauth] → NextAuth handlers → GitHub OAuth
– /api/trpc/[trpc] → tRPC request handler
– /api/examples, /api/restricted → miscellaneous endpoints (e.g. mockAPI proxy)
c. tRPC Layer
- Client-side generated hooks call RPC endpoints
- Server-side context injects session (from NextAuth) and Prisma client
- Routers implement CRUD operations, enforce role checks
d. ORM Layer (Prisma)
- Translates tRPC resolver calls into SQL queries
- Connects to PlanetScale database via DATABASE_URL
e. Database (PlanetScale/MySQL)
- Stores User model (with role field) and other domain data
f. External Services
- GitHub OAuth provider (for login)
- mockAPI endpoint for seeded example data

##### Architectural patterns & design principles
- Hybrid rendering: static generation for public pages, server-side rendering for protected routes.
- RPC pattern: tRPC provides type-safe function calls instead of REST.
- Single codebase separation:
- UI (src/pages, src/styles)
- API handlers (src/pages/api)
- Business logic & data access (src/server)
- Role-based access control enforced at the resolver level.
- Environment-based configuration via src/env and .env files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        UI1["Public List View"]:::frontend
        UI2["Public Detail View"]:::frontend
        UI3["Protected Admin UI"]:::frontend
        UI4["Users Management UI"]:::frontend
        UI5["User Profile (Me)"]:::frontend
        UI6["Candidate Moderator UI"]:::frontend
        UI7["Global App Component"]:::frontend
        UI8["Tailwind Globals"]:::frontend
    end

    %% Next.js Server Layer
    subgraph "Next.js Server" 
        direction TB
        Pages["Next.js Pages & SSR/SSG"]:::backend
        API["API Routes"]:::backend

        subgraph "API Routes"
            direction TB
            AuthAPI["/api/auth/[...nextauth]"]:::backend
            TRPCAPI["/api/trpc/[trpc]"]:::backend
            ExamplesAPI["/api/examples"]:::backend
            RestrictedAPI["/api/restricted"]:::backend
        end
    end

    %% tRPC Layer
    subgraph "tRPC Layer" 
        direction TB
        Context["tRPC Context Builder"]:::backend
        Entry["tRPC Entry Point"]:::backend
        RouterApp["App Router"]:::backend
        RouterAuth["Auth Router"]:::backend
        RouterUsers["Users Router"]:::backend
        RouterMod["Moderator Router"]:::backend
        UtilsClientTRPC["tRPC Client Utilities"]:::frontend
    end

    %% ORM & Database
    subgraph "Prisma ORM" 
        direction TB
        PrismaClient["Prisma Client Setup"]:::backend
        Schema["Prisma Schema"]:::backend
    end
    DB["PlanetScale MySQL"]:::db

    %% Environment & Config
    subgraph "Env & Config" 
        direction TB
        EnvClient["Env Loader (Client)"]:::backend
        EnvServer["Env Loader (Server)"]:::backend
        EnvSchema["Env Schema"]:::backend
        NextConfig["next.config.mjs"]:::backend
        TSConfig["tsconfig.json"]:::backend
        TailwindConfig["tailwind.config.cjs"]:::backend
        PostCSSConfig["postcss.config.cjs"]:::backend
        ESLintConfig[".eslintrc.json"]:::backend
        PrettierConfig["prettier.config.cjs"]:::backend
        NextAuthTypes["NextAuth Types"]:::backend
        UtilsFunctions["Additional Utilities"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHub["GitHub OAuth"]:::external
        MockAPI["mockAPI Service"]:::external
    end

    %% Connections: Client to Server
    UI1 -->|"SSR/SSG Page Fetch"| Pages
    UI2 -->|"SSR/SSG Page Fetch"| Pages
    UI3 -->|"CSR & Protected SSR"| Pages
    UI4 -->|"CSR & Protected SSR"| Pages
    UI5 -->|"CSR & Protected SSR"| Pages
    UI6 -->|"CSR & Protected SSR"| Pages
    UI7 -->|"App Init"| Pages
    UI8 -->|"Styles Load"| Pages

    %% Client to tRPC
    UtilsClientTRPC -->|"tRPC Query/Mutation"| TRPCAPI

    %% OAuth Flow
    UI7 -->|"Login Redirect"| AuthAPI
    AuthAPI -->|"OAuth Redirect"| GitHub
    GitHub -->|"Callback Token"| AuthAPI

    %% API Routes to Handlers
    AuthAPI -->|"Session Handling"| Context
    TRPCAPI -->|"RPC Handler"| Entry
    ExamplesAPI -->|"Proxy Request"| MockAPI
    RestrictedAPI -->|"Proxy Request"| MockAPI

    %% tRPC Entry to Context and Routers
    Entry --> Context
    Context --> RouterAuth
    Context --> RouterUsers
    Context --> RouterMod
    RouterAuth --> RouterApp
    RouterUsers --> RouterApp
    RouterMod --> RouterApp

    %% Routers to ORM
    RouterAuth -->|"DB Query/Mutation"| PrismaClient
    RouterUsers -->|"CRUD Operations"| PrismaClient
    RouterMod -->|"Moderator Ops"| PrismaClient

    %% ORM to Database
    PrismaClient -->|"SQL Queries"| DB
    Schema --> DB

    %% Utility and Config
    Context --> EnvServer
    EnvClient --> UtilsClientTRPC
    EnvSchema --> EnvServer
    NextConfig --> Pages
    TSConfig --> Pages
    TailwindConfig --> UI8
    PostCSSConfig --> UI8
    ESLintConfig --> Pages
    PrettierConfig --> Pages
    NextAuthTypes --> Context
    UtilsFunctions --> Context

    %% Style Classes
    classDef frontend fill:#D6EAFE,stroke:#333,stroke-width:1px
    classDef backend fill:#D4F5D4,stroke:#333,stroke-width:1px
    classDef db fill:#F5D0A9,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px

    %% Click Events
    click UI1 "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/index.tsx"
    click UI2 "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/getdetails/[userId].tsx"
    click UI3 "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/admin/index.tsx"
    click UI4 "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/users/index.tsx"
    click UI5 "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/profile/me/index.tsx"
    click UI6 "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/candidate/moderator.tsx"
    click UI7 "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/_app.tsx"
    click UI8 "https://github.com/moltivie/the-t3-stack/blob/main/src/styles/globals.css"
    click AuthAPI "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/api/auth/[...nextauth].ts"
    click TRPCAPI "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/api/trpc/[trpc].ts"
    click ExamplesAPI "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/api/examples.ts"
    click RestrictedAPI "https://github.com/moltivie/the-t3-stack/blob/main/src/pages/api/restricted.ts"
    click UtilsClientTRPC "https://github.com/moltivie/the-t3-stack/blob/main/src/utils/trpc.ts"
    click UtilsFunctions "https://github.com/moltivie/the-t3-stack/blob/main/src/utils/functions.ts"
    click Schema "https://github.com/moltivie/the-t3-stack/blob/main/prisma/schema.prisma"
    click PrismaClient "https://github.com/moltivie/the-t3-stack/blob/main/src/server/db/client.ts"
    click Context "https://github.com/moltivie/the-t3-stack/blob/main/src/server/trpc/context.ts"
    click Entry "https://github.com/moltivie/the-t3-stack/blob/main/src/server/trpc/trpc.ts"
    click RouterApp "https://github.com/moltivie/the-t3-stack/blob/main/src/server/trpc/router/_app.ts"
    click RouterAuth "https://github.com/moltivie/the-t3-stack/blob/main/src/server/trpc/router/auth.ts"
    click RouterUsers "https://github.com/moltivie/the-t3-stack/blob/main/src/server/trpc/router/users.ts"
    click RouterMod "https://github.com/moltivie/the-t3-stack/blob/main/src/server/trpc/router/moderator.ts"
    click EnvSchema "https://github.com/moltivie/the-t3-stack/blob/main/src/env/schema.mjs"
    click EnvClient "https://github.com/moltivie/the-t3-stack/blob/main/src/env/client.mjs"
    click EnvServer "https://github.com/moltivie/the-t3-stack/blob/main/src/env/server.mjs"
    click NextConfig "https://github.com/moltivie/the-t3-stack/blob/main/next.config.mjs"
    click TSConfig "https://github.com/moltivie/the-t3-stack/blob/main/tsconfig.json"
    click TailwindConfig "https://github.com/moltivie/the-t3-stack/blob/main/tailwind.config.cjs"
    click PostCSSConfig "https://github.com/moltivie/the-t3-stack/blob/main/postcss.config.cjs"
    click ESLintConfig "https://github.com/moltivie/the-t3-stack/blob/main/.eslintrc.json"
    click PrettierConfig "https://github.com/moltivie/the-t3-stack/blob/main/prettier.config.cjs"
    click NextAuthTypes "https://github.com/moltivie/the-t3-stack/blob/main/src/types/next-auth.d.ts"
```
