# vercel/next-forge architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack monorepo template (“next-forge”) built with Turborepo and pnpm.
- It contains multiple Next.js applications (apps/api, apps/app, apps/web, apps/docs, apps/storybook, apps/studio), a suite of shared packages under /packages, build scripts, CI/CD workflows, and infrastructure config.

##### File structure
- Top-level “apps/” directory: each subfolder is a standalone Next.js or Node.js service:
- apps/api: a backend Next.js App Router API with cron jobs, webhooks, global error handling.
- apps/app: the primary authenticated user interface (Next.js with app directory, Liveblocks, PostHog, auth/webhooks).
- apps/web: a public marketing site (multi-locale Next.js).
- apps/docs: documentation site.
- apps/storybook: UI component playground.
- apps/studio: admin or CMS studio interface.
- apps/email: email-sending scripts or templates.
- Top-level “packages/” directory: shareable libraries and tooling modules (authentication, CMS components, database/prisma, analytics, ai, collaboration, design-system, payments, feature-flags, observability, storage, webhooks, etc.).
- Root config files for Turborepo (turbo.json), TypeScript, tsup, CI workflows (.github/workflows), Vercel deployments.

##### README for additional insights
- Confirms it’s a Turborepo template for modern web applications with minimal config.
- Encourages usage of docs site (apps/docs) for deeper architecture and usage.

a. Main components
- User Browsers & Mobile Clients
- Frontend apps:
- Primary App (apps/app)
- Public Web Site (apps/web)
- Docs Site (apps/docs)
- Storybook (apps/storybook)
- Admin Studio (apps/studio)
- Backend API service (apps/api)
- Shared internal libraries (packages/*)
- Database (e.g., PostgreSQL via Prisma in packages/database)
- Email service (apps/email + packages/email)
- External services: Vercel, PostHog, Sentry, Liveblocks, Payment providers, Webhook providers (Svix, etc.)
- CI/CD pipeline (GitHub Actions) and Turborepo orchestrator
b. Relationships & interactions
- Frontend → Backend API (apps/api) for data, auth, webhooks
- API → Database (via Prisma package)
- API → Shared packages (auth, payments, storage, observability)
- API → External services (PostHog for analytics, Sentry for error reporting, Payment providers)
- Cron jobs within API (keep-alive) → external keep-alive endpoint
- apps/email invoked by API or cron → SMTP/external email provider
- UI component sharing: design-system package used by all frontends, storybook hosts those components
- Docs site reads content from docs/content and uses mdx-components
- CI/CD builds all apps/packages in parallel via Turborepo, deploys to Vercel
c. Architectural patterns / principles
- Monorepo with Turborepo for high-performance builds & caching
- Code sharing through internal packages (DRY)
- Next.js App Router for both UI and API routes
- Feature flags, internationalization middleware, security middleware applied at edge/middleware layer
- Separation of concerns: marketing site vs. user app vs. docs vs. admin studio vs. API
d. Relevant technologies / frameworks
- Next.js, React, TypeScript
- Turborepo + pnpm workspaces
- Prisma (packages/database)
- Liveblocks for real-time collaboration
- Feature-flags, PostHog analytics, Sentry observability
- Vercel for deployments, environment routing (.vercel.json)
- Storybook for components
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Clients
    User["User Browsers & Mobile Clients"]:::external

    %% Frontend Layer
    subgraph "Frontend Applications"
        App["Primary Authenticated User Interface"]:::frontend
        Web["Public Marketing Site"]:::frontend
        Docs["Documentation Site"]:::frontend
        Storybook["UI Component Playground"]:::frontend
        Studio["Admin Studio Interface"]:::frontend
    end

    %% Email Service
    Email["Email Service Scripts/Templates"]:::backend

    %% Backend Layer
    subgraph "Backend Service"
        API["Backend API Service"]:::backend
        Cron["Cron Jobs (keep-alive/& scheduled tasks)"]:::backend
    end

    %% Packages Layer
    subgraph "Shared Packages"
        Auth["Authentication Library"]:::packages
        CMS["CMS Components Library"]:::packages
        Analytics["Analytics Module"]:::packages
        AI["AI Components Library"]:::packages
        Collaboration["Real-time Collaboration"]:::packages
        DesignSystem["Design System"]:::packages
        Payments["Payments Integration"]:::packages
        FeatureFlags["Feature Flags"]:::packages
        Observability["Observability & Error Reporting"]:::packages
        Storage["Storage Utilities"]:::packages
        WebhooksLib["Webhooks Handling"]:::packages
        Security["Security Middleware & Utilities"]:::packages
        Notifications["Notifications System"]:::packages
        I18n["Internationalization Middleware"]:::packages
        SEO["SEO Utilities"]:::packages
        RateLimit["Rate Limiting"]:::packages
        NextConfig["Shared Next.js Configuration"]:::packages
        Testing["Testing Utilities"]:::packages
        TSConfig["TypeScript Config Presets"]:::packages
        DatabasePkg["Database Integration (Prisma)"]:::packages
    end

    %% Data Store
    DB["Database (PostgreSQL)"]:::external

    %% External Services
    subgraph "External Services"
        PH["PostHog (Analytics)"]:::external
        Sentry["Sentry (Error Reporting)"]:::external
        PaymentsExt["Payment Providers"]:::external
        SMTP["External Email Provider"]:::external
        WebhookProv["Webhook Providers (Svix)"]:::external
        LiveblocksExt["Liveblocks (Real-time)"]:::external
    end

    %% Infra
    CI["CI/CD & Turborepo"]:::infra
    Vercel["Vercel Deployment"]:::infra

    %% Relationships
    User --> App
    User --> Web
    App --> API
    Web --> API
    Docs --> API
    Studio --> API
    Storybook --> DesignSystem
    API --> DatabasePkg
    API --> Auth
    API --> CMS
    API --> Analytics
    API --> AI
    API --> Collaboration
    API --> DesignSystem
    API --> Payments
    API --> FeatureFlags
    API --> Observability
    API --> Storage
    API --> WebhooksLib
    API --> Security
    API --> Notifications
    API --> I18n
    API --> SEO
    API --> RateLimit
    API --> NextConfig
    API --> Testing
    API --> TSConfig
    DatabasePkg --> DB
    API --> PH
    API --> Sentry
    API --> PaymentsExt
    API --> WebhookProv
    API --> LiveblocksExt
    API --> Email
    Cron --> Email
    Email --> SMTP

    CI --> App
    CI --> Web
    CI --> Docs
    CI --> Storybook
    CI --> Studio
    CI --> API
    CI --> Vercel
    Vercel --> App
    Vercel --> Web
    Vercel --> Docs
    Vercel --> Storybook
    Vercel --> Studio
    Vercel --> API

    %% Click Events
    click App "https://github.com/vercel/next-forge/tree/main/apps/app"
    click Web "https://github.com/vercel/next-forge/tree/main/apps/web"
    click Docs "https://github.com/vercel/next-forge/tree/main/apps/docs"
    click Storybook "https://github.com/vercel/next-forge/tree/main/apps/storybook"
    click Studio "https://github.com/vercel/next-forge/tree/main/apps/studio"
    click Email "https://github.com/vercel/next-forge/tree/main/apps/email"
    click API "https://github.com/vercel/next-forge/tree/main/apps/api"
    click DatabasePkg "https://github.com/vercel/next-forge/tree/main/packages/database"
    click Auth "https://github.com/vercel/next-forge/tree/main/packages/auth"
    click CMS "https://github.com/vercel/next-forge/tree/main/packages/cms"
    click Analytics "https://github.com/vercel/next-forge/tree/main/packages/analytics"
    click AI "https://github.com/vercel/next-forge/tree/main/packages/ai"
    click Collaboration "https://github.com/vercel/next-forge/tree/main/packages/collaboration"
    click DesignSystem "https://github.com/vercel/next-forge/tree/main/packages/design-system"
    click Payments "https://github.com/vercel/next-forge/tree/main/packages/payments"
    click FeatureFlags "https://github.com/vercel/next-forge/tree/main/packages/feature-flags"
    click Observability "https://github.com/vercel/next-forge/tree/main/packages/observability"
    click Storage "https://github.com/vercel/next-forge/tree/main/packages/storage"
    click WebhooksLib "https://github.com/vercel/next-forge/tree/main/packages/webhooks"
    click Security "https://github.com/vercel/next-forge/tree/main/packages/security"
    click Notifications "https://github.com/vercel/next-forge/tree/main/packages/notifications"
    click I18n "https://github.com/vercel/next-forge/tree/main/packages/internationalization"
    click SEO "https://github.com/vercel/next-forge/tree/main/packages/seo"
    click RateLimit "https://github.com/vercel/next-forge/tree/main/packages/rate-limit"
    click NextConfig "https://github.com/vercel/next-forge/tree/main/packages/next-config"
    click Testing "https://github.com/vercel/next-forge/tree/main/packages/testing"
    click TSConfig "https://github.com/vercel/next-forge/tree/main/packages/typescript-config"
    click CI "https://github.com/vercel/next-forge/blob/main/turbo.json"
    click CI "https://github.com/vercel/next-forge/blob/main/.github/workflows/build.yml"
    click CI "https://github.com/vercel/next-forge/blob/main/.github/workflows/release.yml"
    click CI "https://github.com/vercel/next-forge/blob/main/pnpm-workspace.yaml"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef backend fill:#9cf,stroke:#333,stroke-width:1px
    classDef packages fill:#fc9,stroke:#333,stroke-width:1px
    classDef external fill:#c9f,stroke:#333,stroke-width:1px
    classDef infra fill:#9f9,stroke:#333,stroke-width:1px
```
