# vercel/platforms architecture

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

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

## Overview

##### Main Components of the System
- Frontend (Client-Side UI):
- Next.js pages and layouts: The “app” directory hosts all page routes, organized by domain (dynamic routing for “[domain]” and “[slug]”) and differentiated areas such as the public site, authentication, and dashboard.
- Dashboard and Blog UI components: Under “app/app/(dashboard)” and “components”, you have various React components for site management, posts, analytics, and blog display.

- Backend (Server/API):
- API Routes: The “app/api” directory bundles RESTful endpoints for authentication (via NextAuth), domain verification, image upload, post/site generation, and migration.
- Business Logic & Helpers: The “lib” directory contains modules for database interactions (using Drizzle ORM), authentication utilities, domain handling, custom actions, and general helper utilities.
- Middleware: “middleware.ts” allows handling incoming requests (e.g., for authentication, route protections, or multi-tenant redirection).

- External Services:
- Database: Vercel Postgres is used for data persistence. The project’s DB operations are abstracted in “lib/db.ts” (and associated schema and migration scripts).
- External APIs: Vercel Domains API is employed to manage custom/subdomains and SSL, and Vercel Blob is used for handling image storage.
- Authentication: NextAuth.js manages authentication flows, with its configuration available under “app/api/auth/[...nextauth]” routes.
- AI and Third-Party Integrations: The project uses Novel for its AI-powered Markdown editor, and external charting libraries like Tremor.

##### Relationships and Interactions
- The Frontend communicates with the Backend through:
- Serverless API calls (e.g., for auth, domain verification, image uploads).
- Page routing that dynamically renders content based on subdomains and slugs (multi-tenant routing logic).
- The “lib” modules serve as a bridge between the API routes and external services:
- For instance, database actions are handled by functions in “lib/db.ts” and “lib/schema.ts” using Drizzle.
- External services are connected via clearly defined API layers:
- Vercel Postgres for database operations.
- Vercel Domains API for managing custom domains.
- Vercel Blob for image upload endpoints.
- The Middleware ensures pre-request handling such as authentication checks or tenant identification.

##### Architectural Patterns & Principles
- File-based Routing & Dynamic Segmentation: The file tree shows a structured usage of dynamic routes (e.g., “[domain]”, “[slug]”) and grouping pages under feature-based segments (like dashboard and auth).
- Separation of Concerns: The application cleanly separates:
- UI Components (under “components” and “app”) for presentation.
- Business Logic and utilities (under “lib”).
- API Handlers (under “app/api”) for backend operations.
- Multi-Tenancy: The routing and backend logic cater to multiple tenants via domain-specific layouts and API endpoints with specialized routes for domain verification and content generation.
- Serverless Deployment: API routes are designed for serverless environments, deployed on Vercel.

##### Elements
- Components and labels:
- Detailed Annotations:
- Annotations to highlight dynamic routing aspects, multi-tenancy support, and serverless deployment patterns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraphs
    subgraph "Frontend"
        subgraph "Next.js Pages & Layouts"
            FN1["App (Next.js Routes)"]
            FN2["Domain Route (app/[domain])"]
            FN3["Slug Route (app/[domain]/[slug])"]
            FN4["Layout (app/layout.tsx)"]
            FN5["Providers (app/providers.tsx)"]
            FN6["Home Page (app/home/page.tsx)"]
            FN7["Sitemap (app/sitemap.ts)"]
        end
        subgraph "UI Components"
            FC1["Auth UI (app/app/(auth))"]
            FC2["Dashboard UI (app/app/(dashboard))"]
            FC3["Shared Components (components)"]
        end
    end

    %% Middleware & Backend API Subgraphs
    subgraph "Middleware & API Gateway"
        MW["Middleware (middleware.ts)"]:::middleware
        subgraph "Backend API"
            BA1["Authentication API (app/api/auth)"]:::api
            BA2["Domain Verification API (app/api/domain)"]:::api
            BA3["Generate API (app/api/generate/route.ts)"]:::api
            BA4["Migration API (app/api/migrate/route.ts)"]:::api
            BA5["Upload API (app/api/upload/route.ts)"]:::api
        end
    end

    %% Business Logic & Helpers Subgraph
    subgraph "Business Logic & Helpers"
        BL1["Core Modules (lib)"]:::business
        BL2["Custom Hooks (lib/hooks)"]:::business
        BL3["Utilities (lib/utils.ts)"]:::business
    end

    %% External Services Subgraph
    subgraph "External Services"
        ES1["Vercel Postgres"]:::external
        ES2["Vercel Blob"]:::external
        ES3["Vercel Domains API"]:::external
        ES4["NextAuth"]:::external
        ES5["Novel Editor"]:::external
        ES6["Tremor Charts"]:::external
    end

    %% Connections: Frontend to Middleware
    FN1 --> MW
    FN2 --> MW
    FN3 --> MW
    FN4 --> MW
    FN5 --> MW
    FN6 --> MW
    FN7 --> MW
    FC1 --> MW
    FC2 --> MW
    FC3 --> MW

    %% Connections: Middleware to Backend API
    MW --> BA1
    MW --> BA2
    MW --> BA3
    MW --> BA4
    MW --> BA5

    %% Connections: Backend API to Business Logic
    BA1 --> BL1
    BA2 --> BL1
    BA3 --> BL1
    BA4 --> BL1
    BA5 --> BL1

    %% Specific API to External Services links
    BA1 --> ES4
    BA2 --> ES3
    BA5 --> ES2
    BL1 --> ES1

    %% Additional UI integrations with External Services
    FC3 --> ES5
    FC2 --> ES6

    %% Internal Business Logic links
    BL2 --> BL1
    BL3 --> BL1

    %% Class Definitions for Styling
    classDef frontend fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef api fill:#C0E6F8,stroke:#333,stroke-width:2px;
    classDef business fill:#D1F7C4,stroke:#333,stroke-width:2px;
    classDef external fill:#F9D1D1,stroke:#333,stroke-width:2px;
    classDef middleware fill:#FCE1A4,stroke:#333,stroke-width:2px;

    %% Apply Classes
    class FN1,FN2,FN3,FN4,FN5,FN6,FN7,FC1,FC2,FC3 frontend;
    class BA1,BA2,BA3,BA4,BA5 api;
    class BL1,BL2,BL3 business;
    class ES1,ES2,ES3,ES4,ES5,ES6 external;

    %% Click Events for Frontend - Next.js Pages & Layouts
    click FN1 "https://github.com/vercel/platforms/tree/main/app"
    click FN2 "https://github.com/vercel/platforms/tree/main/app/[domain]"
    click FN3 "https://github.com/vercel/platforms/tree/main/app/[domain]/[slug]"
    click FN4 "https://github.com/vercel/platforms/blob/main/app/layout.tsx"
    click FN5 "https://github.com/vercel/platforms/blob/main/app/providers.tsx"
    click FN6 "https://github.com/vercel/platforms/blob/main/app/home/page.tsx"
    click FN7 "https://github.com/vercel/platforms/blob/main/app/sitemap.ts"

    %% Click Events for UI Components
    click FC1 "https://github.com/vercel/platforms/tree/main/app/app/(auth)"
    click FC2 "https://github.com/vercel/platforms/tree/main/app/app/(dashboard)"
    click FC3 "https://github.com/vercel/platforms/tree/main/components"

    %% Click Events for Backend API
    click BA1 "https://github.com/vercel/platforms/tree/main/app/api/auth"
    click BA2 "https://github.com/vercel/platforms/tree/main/app/api/domain"
    click BA3 "https://github.com/vercel/platforms/blob/main/app/api/generate/route.ts"
    click BA4 "https://github.com/vercel/platforms/blob/main/app/api/migrate/route.ts"
    click BA5 "https://github.com/vercel/platforms/blob/main/app/api/upload/route.ts"

    %% Click Events for Business Logic & Helpers
    click BL1 "https://github.com/vercel/platforms/tree/main/lib"
    click BL2 "https://github.com/vercel/platforms/tree/main/lib/hooks"
    click BL3 "https://github.com/vercel/platforms/blob/main/lib/utils.ts"

    %% Click Event for Middleware
    click MW "https://github.com/vercel/platforms/blob/main/middleware.ts"
```
