# vercel/next-learn architecture

> Architecture diagram of the GitHub repository vercel/next-learn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vercel/next-learn
- Repository: https://github.com/vercel/next-learn

## Overview

##### Project Type and Purpose
- This is a monorepo containing multiple Next.js example applications used in the “Learn Next.js” courses:
- basics (Pages Router starters + finals, TypeScript, dynamic routes, data fetching)
- dashboard (App Router–based starter + final examples with Auth, data seeding, CRUD)
- seo (Pages Router SEO tutorials and demo)
- Each folder under `basics/`, `dashboard/`, and `seo/` is a standalone full-stack Next.js app demonstrating core concepts (SSG/SSR, API routes, App Router, Auth, Tailwind, TypeScript).

##### File-Structure Analysis
- Top-Level: monorepo root with versioning/config (`package.json`, `pnpm-lock.yaml`, lint/prettier configs).
- Subprojects:
- basics/…: multiple iterations of starter + final apps under pages-router.
- dashboard/…: two App Router apps (`starter-example` and `final-example`) with `/app`, `/app/lib`, `/app/ui`, `/app/query`, `/app/seed`, plus middleware, auth config, Tailwind.
- seo/…: pages-router SEO examples.
- Build/Deploy: each app has its own `package.json`, uses Next.js build scripts, optional `.env`, and deploy targets (Vercel).

##### Key Architectural Patterns & Tech
- Next.js file-system routing for both pages (`/pages`) and App Router (`/app`).
- Component-based UI under `/components` or `/app/ui`.
- Data-fetching abstractions in `/lib` or `/app/lib` (placeholder data, actions, route handlers).
- API Routes under `/pages/api` or route handlers under `/app/query` & `/app/seed`.
- CSS Modules, global CSS, and Tailwind CSS.
- Optional TypeScript with type declarations and `tsconfig.json`.
- Auth & middleware in the dashboard final example.

- Client (Browser)
- Executes React components, hydration, CSR navigation.
- Next.js Server
- Serves SSR/SSG pages, runs API routes/route handlers, middleware.
- Routing Layer
- File-based routes (`/pages/*`, `/app/*`) → rendering strategies (SSG, SSR, RSC).
- API Layer
- `/pages/api/*` or `/app/query/route.ts` & `/app/seed/route.ts`.
- Data Layer
- `/lib/*` modules: in-memory placeholder data, fetch utilities, actions.
- UI Component Library
- Shared UI primitives under `/components` or `/app/ui` (buttons, tables, forms).
- Public Assets
- Static images/CSS under `/public`.
- Configuration
- `next.config.js`, `tailwind.config.js`, `auth.config.ts` for middleware/auth.
- External Services (dashboard final)
- Auth provider (in-memory or third-party), Vercel edge functions (middleware).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Root
    subgraph "Monorepo Root"
        PKG["package.json"]:::config
        LOCK["pnpm-lock.yaml"]:::config
        ESL[".eslintrc.js"]:::config
        PRET["prettier.config.js"]:::config
    end

    %% Project Modules
    subgraph "Basics Examples" 
        BASICS["/basics"]:::repo
    end

    subgraph "Dashboard Examples"
        subgraph "Starter Example"
            StarterEntry["App Entry"]:::server
            StarterPage["Routing Layer\n(page.tsx)"]:::server
            QueryStarter["API Query Handler"]:::server
            SeedStarter["API Seed Handler"]:::server
            DataLibStarter["Data Lib"]:::data
            UIStarter["UI Components"]:::frontend
            NextConfigStarter["next.config.ts"]:::config
            TailwindStarter["tailwind.config.ts"]:::config
        end
        subgraph "Final Example"
            FinalEntry["App Layout\n(layout.tsx)"]:::server
            DashPages["Dashboard Pages"]:::server
            Login["Login Page\n(page.tsx)"]:::server
            QueryFinal["API Query Handler"]:::server
            SeedFinal["API Seed Handler"]:::server
            DataLibFinal["Data Lib & Actions"]:::data
            UIFinal["UI Components"]:::frontend
            AuthConfig["Auth Config"]:::config
            Middleware["Middleware"]:::server
            NextConfigFinal["next.config.ts"]:::config
            TailwindFinal["tailwind.config.ts"]:::config
            EnvExample[".env.example"]:::static
        end
    end

    subgraph "SEO Examples"
        SEOStaticPages["Static SEO Pages"]:::server
        SEODemoPages["Demo App Pages"]:::server
    end

    %% Detailed Single-App View for Dashboard Final Example
    subgraph "Browser (Client)" 
        Browser["Browser"]:::frontend
    end

    subgraph "Next.js Server" 
        Routing["Routing Layer\n(SSG/SSR/RSC)"]:::server
        APILayer["API Layer\n(routes & handlers)"]:::server
        MiddlewareAuth["Middleware & Auth"]:::server
    end

    subgraph "Server Internals"
        DataLibFinal
        UIFinal
        PublicAssets["Public Assets"]:::static
    end

    subgraph "External Services"
        AuthProvider["Auth Provider"]:::external
        VercelEdge["Vercel Edge Functions"]:::external
    end

    %% Connections
    Browser -->|"page request"| Routing
    Routing -->|"fetch data"| DataLibFinal
    Routing -->|"invoke API"| APILayer
    Routing -->|"apply"| MiddlewareAuth
    APILayer -->|"CRUD ops"| DataLibFinal
    MiddlewareAuth -->|checks| AuthProvider
    MiddlewareAuth -->|deploy| VercelEdge

    %% Click Events
    click PKG "https://github.com/vercel/next-learn/blob/main//package.json"
    click LOCK "https://github.com/vercel/next-learn/blob/main//pnpm-lock.yaml"
    click ESL "https://github.com/vercel/next-learn/blob/main//.eslintrc.js"
    click PRET "https://github.com/vercel/next-learn/blob/main//prettier.config.js"
    click BASICS "https://github.com/vercel/next-learn/tree/main//basics"
    click StarterEntry "https://github.com/vercel/next-learn/tree/main//dashboard/starter-example/app"
    click StarterPage "https://github.com/vercel/next-learn/blob/main//dashboard/starter-example/app/page.tsx"
    click QueryStarter "https://github.com/vercel/next-learn/blob/main//dashboard/starter-example/app/query/route.ts"
    click SeedStarter "https://github.com/vercel/next-learn/blob/main//dashboard/starter-example/app/seed/route.ts"
    click DataLibStarter "https://github.com/vercel/next-learn/tree/main//dashboard/starter-example/app/lib"
    click UIStarter "https://github.com/vercel/next-learn/tree/main//dashboard/starter-example/app/ui"
    click NextConfigStarter "https://github.com/vercel/next-learn/blob/main//dashboard/starter-example/next.config.ts"
    click TailwindStarter "https://github.com/vercel/next-learn/blob/main//dashboard/starter-example/tailwind.config.ts"
    click FinalEntry "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/app/layout.tsx"
    click DashPages "https://github.com/vercel/next-learn/tree/main//dashboard/final-example/app/dashboard"
    click Login "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/app/login/page.tsx"
    click QueryFinal "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/app/query/route.ts"
    click SeedFinal "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/app/seed/route.ts"
    click DataLibFinal "https://github.com/vercel/next-learn/tree/main//dashboard/final-example/app/lib"
    click UIFinal "https://github.com/vercel/next-learn/tree/main//dashboard/final-example/app/ui"
    click AuthConfig "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/auth.config.ts"
    click Middleware "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/middleware.ts"
    click NextConfigFinal "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/next.config.ts"
    click TailwindFinal "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/tailwind.config.ts"
    click EnvExample "https://github.com/vercel/next-learn/blob/main//dashboard/final-example/.env.example"
    click SEOStaticPages "https://github.com/vercel/next-learn/tree/main//seo/pages"
    click SEODemoPages "https://github.com/vercel/next-learn/tree/main//seo/demo/pages"

    %% Styles
    classDef config fill:#f9f,stroke:#333,stroke-width:1px
    classDef repo fill:#eef,stroke:#333,stroke-width:1px
    classDef frontend fill:#8fd,stroke:#333,stroke-width:1px
    classDef server fill:#afa,stroke:#333,stroke-width:1px
    classDef data fill:#ff8,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
    classDef static fill:#fcf,stroke:#333,stroke-width:1px
```
