# episerver/cms-saas-vercel-demo architecture

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

- Interactive diagram: https://gitdiagram.com/episerver/cms-saas-vercel-demo
- Repository: https://github.com/episerver/cms-saas-vercel-demo

## Overview

##### Project type and purpose
- This is a monorepo hosting a full-stack web application demo site built in Next.js that uses Optimizely SaaS CMS as a headless content source. It also contains a CLI tool for scaffolding new sites (under `packages/remkoj-optimizely-fx-nextjs-cli`).

##### File structure
- Top-level:
- Yarn workspace configuration (`.yarnrc.yml`, `.yarn/`, `package.json`, `tsconfig.json`)
- `apps/` – application code
– `apps/frontend/` – the Next.js front-end
– `apps/old_cms_types/` – legacy CMS type definitions (fallback code)
- `packages/` – npm packages
– `remkoj-optimizely-fx-nextjs-cli/` – a CLI for setting up Optimizely-One-Next.js projects
- `docs/` and `content-updates/` – documentation and data migrations
- Notice Next.js conventions in `apps/frontend/src/app` (file-based routing and API routes), GraphQL codegen config, PostCSS, Tailwind, ESLint, Prettier SDKs.

##### README for additional insights
- The front-end pulls content at build-time or run-time from the Optimizely Content Graph (GraphQL endpoint) using environment variables (`OPTIMIZELY_CMS_URL`, `OPTIMIZELY_GRAPH_*`).
- It’s deployed to Vercel (see `vercel.json` and README deploy instructions).
- It supports preview, static generation, client-side fetches, and on-page editing.

##### Main components of the system
a. Monorepo (Yarn workspaces)
b. CLI package (`remkoj-optimizely-fx-nextjs-cli`) – developer tool used locally at “build time” to scaffold new sites
c. Frontend application (`apps/frontend`)
- Next.js server (SSR/SSG) + React components
- File-based routing (`src/app/[[...path]]`, API routes in `src/app/api/...`)
- GraphQL codegen & client (`gql/`, `codegen.ts`)
- Static assets (in `public/`)
- Styling (Tailwind in `tailwind.config.ts`, PostCSS, SCSS)
d. Optimizely CMS Content Graph (external GraphQL service)
e. Vercel (build pipeline & hosting)
f. Optional external services (e.g., Content Recommendations, Analytics integrations)

##### Relationships and interactions
- Build time:
- Developer invokes Yarn in root → installs workspaces → runs codegen in `apps/frontend` → Next.js build → output (static assets + serverless functions) → Vercel
- CLI package installed globally or via `yarn workspace` to scaffold new projects
- Runtime (user request flow):
1. Browser → Vercel Edge → Next.js serverless function (SSR/SSG) or static host
2. If SSR or fallback, Next.js calls GraphQL client → Optimizely CMS Content Graph → returns JSON content
3. Next.js renders page → HTML & JSON → Browser
4. In-page React components may fetch further dynamic data (search, “me”, preview) via built-in API routes → Next.js → CMS or other external services
5. Browser-side feature flags (via `useFlag.ts`) and analytics (“google-analytics.tsx”)

##### Architectural patterns and principles
- Monorepo with Yarn workspaces for code sharing
- File-based routing (Next.js app router) + API routes for serverless micro-endpoints
- GraphQL code generation for type-safe CMS queries
- Component-driven UI mapped to CMS content types (CMS components, experiences, media, page templates)
- Static & dynamic hybrid rendering (SSG with ISR, SSR for preview)
- Clear separation of concerns: components vs. layout vs. API vs. integrations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entities
    Developer["Developer Workstation"]:::external
    Browser["End User Browser"]:::external
    OptiCMS["Optimizely CMS Content Graph"]:::external
    VercelEdge["Vercel Edge"]:::external

    subgraph "Monorepo Workspace" 
        direction TB
        Monorepo["Monorepo Root\n(Yarn Workspaces)"]:::internal
        CLI["CLI Package\n(remkoj-optimizely-fx-nextjs-cli)"]:::internal
        LegacyTypes["Legacy CMS Types\n(apps/old_cms_types)"]:::internal
        subgraph "Docs & Migrations"
            direction TB
            Docs["Documentation\n(/docs)"]:::internal
            Migrations["Data Migrations\n(/content-updates)"]:::internal
        end
    end

    subgraph "Frontend Application" 
        direction TB
        subgraph "Source & Routing"
            SrcRoutes["File-Based Routing\n(/apps/frontend/src/app/)"]:::internal
            APIRoutes["API Routes\n(/apps/frontend/src/app/api/)"]:::internal
        end
        subgraph "GraphQL"
            Codegen["Codegen Config\n(/apps/frontend/codegen.ts)"]:::build
            GQLClient["GraphQL Client\n(/apps/frontend/gql/)"]:::build
        end
        StaticAssets["Static Assets\n(/apps/frontend/public/)"]:::internal
        subgraph "Styling"
            Tailwind["Tailwind Config\n(/apps/frontend/tailwind.config.ts)"]:::internal
            PostCSS["PostCSS Config\n(/apps/frontend/postcss.config.js)"]:::internal
        end
        subgraph "Next.js Config & Env"
            NextConfig["Next.js Config\n(/apps/frontend/next.config.js)"]:::internal
            Env["Environment Vars\n(/apps/frontend/.env)"]:::internal
            FrontVercelCfg["Vercel Config\n(/apps/frontend/vercel.json)"]:::internal
        end
    end

    subgraph "Vercel Deployment"
        direction TB
        VercelRootCfg["Root Vercel Config\n(/vercel.json)"]:::internal
        BuildPipeline["Build Pipeline\n(Codegen → Bundler → Next.js Build)"]:::build
        Runtime["Runtime\n(SSR/SSG & API Routes)"]:::runtime
    end

    %% Flows
    Developer -->|uses| CLI
    CLI -->|scaffold| Monorepo
    Monorepo -->|workspace install| BuildPipeline
    BuildPipeline -->|deploy| VercelDeployment[Vercel Deployment]
    BuildPipeline -->|outputs to| VercelEdge
    VercelEdge -->|route request| Runtime
    Runtime -->|fetch content| OptiCMS
    OptiCMS -->|return JSON| Runtime
    Runtime -->|render page| Browser
    Browser -->|initial request| VercelEdge
    Browser -->|calls API| Runtime
    Runtime -->|API fetch| OptiCMS
    Browser -->|client-side fetch| APIRoutes

    %% Monorepo contains frontend
    Monorepo --> FrontendApplication["Frontend Application"]
    Monorepo --> LegacyTypes
    Monorepo --> Docs
    Monorepo --> Migrations

    %% Frontend structure
    FrontendApplication --> SrcRoutes
    FrontendApplication --> APIRoutes
    FrontendApplication --> Codegen
    FrontendApplication --> GQLClient
    FrontendApplication --> StaticAssets
    FrontendApplication --> Tailwind
    FrontendApplication --> PostCSS
    FrontendApplication --> NextConfig
    FrontendApplication --> Env
    FrontendApplication --> FrontVercelCfg

    %% Click Events
    click Monorepo "https://github.com/episerver/cms-saas-vercel-demo/blob/main//package.json"
    click CLI "https://github.com/episerver/cms-saas-vercel-demo/tree/main//packages/remkoj-optimizely-fx-nextjs-cli/"
    click LegacyTypes "https://github.com/episerver/cms-saas-vercel-demo/tree/main//apps/old_cms_types/"
    click Docs "https://github.com/episerver/cms-saas-vercel-demo/tree/main//docs/"
    click Migrations "https://github.com/episerver/cms-saas-vercel-demo/tree/main//content-updates/"
    click SrcRoutes "https://github.com/episerver/cms-saas-vercel-demo/tree/main//apps/frontend/src/app/"
    click APIRoutes "https://github.com/episerver/cms-saas-vercel-demo/tree/main//apps/frontend/src/app/api/"
    click Codegen "https://github.com/episerver/cms-saas-vercel-demo/blob/main//apps/frontend/codegen.ts"
    click GQLClient "https://github.com/episerver/cms-saas-vercel-demo/tree/main//apps/frontend/gql/"
    click StaticAssets "https://github.com/episerver/cms-saas-vercel-demo/tree/main//apps/frontend/public/"
    click Tailwind "https://github.com/episerver/cms-saas-vercel-demo/blob/main//apps/frontend/tailwind.config.ts"
    click PostCSS "https://github.com/episerver/cms-saas-vercel-demo/blob/main//apps/frontend/postcss.config.js"
    click NextConfig "https://github.com/episerver/cms-saas-vercel-demo/blob/main//apps/frontend/next.config.js"
    click Env "https://github.com/episerver/cms-saas-vercel-demo/blob/main//apps/frontend/.env"
    click FrontVercelCfg "https://github.com/episerver/cms-saas-vercel-demo/blob/main//apps/frontend/vercel.json"
    click VercelRootCfg "https://github.com/episerver/cms-saas-vercel-demo/blob/main//vercel.json"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px
    classDef external fill:#D5F5E3,stroke:#145A32,stroke-width:1px
    classDef build fill:#FADBD8,stroke:#922B21,stroke-width:1px
    classDef runtime fill:#FCF3CF,stroke:#7D6608,stroke-width:1px
```
