# cyr17/action-lab-website architecture

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

- Interactive diagram: https://gitdiagram.com/cyr17/action-lab-website
- Repository: https://github.com/cyr17/action-lab-website

## Overview

##### Project Type & Purpose
- This is a full-stack website template that includes both a production-ready frontend (built with Next.js using the new App Router) and a robust backend powered by Payload CMS. The project is designed to manage websites, blogs, or portfolios with features like layout building, authentication, access control, SEO, media management, and draft/live preview capabilities. The system supports content publishing, customizable pages/posts, and even a pre-built admin panel.

##### Analyzing the File Structure
- Top-Level Organization: Notice many config files (e.g., Dockerfile, next.config.js, tsconfig.json, package.json) that manage project build, coding standards, and environment settings.
- The project is organized under a main “src” directory, which further splits into:
- "src/app": Contains two clear segments:
– (frontend): Houses Next.js page components, layouts, global CSS, and various routes serving the public site.
– (payload): Contains routes and admin panel components including API endpoints (e.g., for GraphQL and redirects), styling, and custom logic.
- "src/blocks", "src/components", "src/heros", etc.: These directories hold reusable UI components and layout blocks used both for the frontend page rendering and the Payload CMS-driven content management.
- "src/payload" outside of the “app”: Contains backend-specific code such as collections, globals, fields, access control modules, hooks, and utilities. This portion defines the CMS behavior for Users, Posts, Pages, Media, and Categories.
- Presence of Docker and docker-compose files indicates support for containerized deployment environments.

##### Key Components
a. Frontend (Next.js App):
- Next.js Application Routes: Show “src/app/(frontend)” containing pages, dynamic routes ([slug]), layouts, and globals.
- Static Assets & Styling: Reference public assets, global CSS, TailwindCSS configuration, and component-level styles.
- UI Components & Blocks: Include major UI components (e.g., Header, Footer, Hero, Cards) and layout blocks (e.g., ArchiveBlock, CallToAction) that make up the page structure.
b. Backend (Payload CMS):
- Payload Configuration: Represent the configuration files (src/payload/config.ts, payload-types.ts, etc.) that set up the CMS collections (Users, Posts, Pages, Media, Categories) and globals (Header, Footer, MegaMenu, etc.).
- API Endpoints: Illustrate the API routes in src/app/(payload)/api for custom endpoints (GraphQL, graphql-playground, and others) and note the usage of REST and GraphQL.
- Hooks & Utility Modules: Highlight middleware components such as afterChange hooks (for draft/live preview) and other utilities provided for content preview, revalidation, and access control.
c. Shared Components & Integrations:
- Layout Builder: A central design concept that connects both frontend (dynamic page layouts) and payload collections. Show how content blocks (hero, media, content, etc.) are interchanged between the two.
- External Services: Indicate integrations with third-party services like Cloudflare (via the Cloud Plugin) for caching, environment variables management (using .env), and authentication services.

##### Relationships & Data Flows
- User Interaction: Users interact with the frontend UI as well as the Payload Admin Panel.
- Data & Content Flow: Content and configuration data from the Payload backend (collections, globals) are pushed to the frontend to generate pages either via static generation or server-side rendering.
- API Communication: The frontend communicates with backend API endpoints (located in the payload API directory) to fetch dynamic data, handle authentication, and manage drafts.
- Admin Operations: Administrators utilize the Payload admin panel to create, update, publish, and seed content which then triggers hooks for revalidation or cache updates.

##### Architectural Patterns & Design Principles
- Full-Stack Separation: Emphasize the clear separation between the frontend and backend. Although they reside in a single codebase under distinct folders, their responsibilities and deployment strategies are modular.
- Component-Based UI: Leverage Next.js and React’s component model to compose UIs from discrete, reusable blocks.
- CMS-Driven Content: The backend is built around Payload CMS’s collection system, utilizing hooks and access control to manage content life cycles.
- API Gateway: The API endpoints under (payload)/api act as a gateway between the frontend (or external services) and the payload data store.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interaction Layer
    subgraph "Client Interaction Layer"
        Users["Clients (Web Browsers)"]:::client
        AdminUsers["Admin Users"]:::client
    end

    %% Frontend UI - Next.js App
    subgraph "Frontend UI - Next.js App"
        FE["Next.js Pages/Routes"]:::frontend
        Components["UI Components & Blocks"]:::frontend
        Heros["Hero Components"]:::frontend
        Providers["Context Providers"]:::frontend
        StaticAssets["Static Assets & Styling"]:::frontend
    end

    %% Shared Components
    subgraph "Shared Components"
        LayoutBuilder["Layout Builder (Shared)"]:::shared
    end

    %% Backend - Payload CMS
    subgraph "Backend - Payload CMS"
        PayloadConfig["Payload Config & Types"]:::backend
        PayloadBackend["Payload Backend Code"]:::backend
        Collections["Collections"]:::backend
        CMSGlobals["Globals"]:::backend
        Fields["Fields"]:::backend
        Hooks["Hooks & Utilities"]:::backend
        Utilities["Utilities"]:::backend
        AdminPanel["Admin Panel"]:::backend
    end

    %% Payload API Endpoints
    subgraph "Payload API"
        API_Base["Base API Endpoints"]:::api
        API_Slug["Catch-all API Route"]:::api
        API_Playground["GraphQL Playground"]:::api
        API_GraphQL["GraphQL API"]:::api
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Docker["Docker & Containerization"]:::infrastructure
        Cloudflare["Cloudflare & External Services"]:::infrastructure
    end

    %% Connections
    Users -->|"request"| FE
    FE -->|"fetch_data"| API_Base
    API_Base -->|"includes"| API_Slug
    API_Base -->|"includes"| API_Playground
    API_Base -->|"includes"| API_GraphQL
    AdminUsers -->|"manage"| AdminPanel
    AdminPanel -->|"trigger"| Hooks
    Hooks -->|"invoke"| Cloudflare
    Components -->|"uses"| LayoutBuilder
    Heros -->|"integrates"| LayoutBuilder
    Collections -->|"populate"| LayoutBuilder
    LayoutBuilder -->|"drives_layout"| FE
    PayloadConfig -->|"defines"| Collections
    PayloadConfig -->|"defines"| CMSGlobals
    PayloadConfig -->|"defines"| Hooks
    PayloadBackend -->|"contains"| PayloadConfig
    PayloadBackend -->|"contains"| Collections
    PayloadBackend -->|"contains"| CMSGlobals
    PayloadBackend -->|"contains"| Fields
    PayloadBackend -->|"contains"| Hooks
    PayloadBackend -->|"contains"| Utilities
    Docker --- FE
    Docker --- PayloadConfig
    Docker --- API_Base
    Cloudflare --- FE

    %% Click Events
    click FE "https://github.com/cyr17/action-lab-website/tree/master/src/app/(frontend)"
    click Components "https://github.com/cyr17/action-lab-website/tree/master/src/app/components"
    click Heros "https://github.com/cyr17/action-lab-website/tree/master/src/app/heros"
    click Providers "https://github.com/cyr17/action-lab-website/tree/master/src/app/providers"
    click LayoutBuilder "https://github.com/cyr17/action-lab-website/tree/master/src/app/blocks"
    click PayloadConfig "https://github.com/cyr17/action-lab-website/blob/master/src/payload.config.ts"
    click PayloadBackend "https://github.com/cyr17/action-lab-website/tree/master/src/payload"
    click Collections "https://github.com/cyr17/action-lab-website/tree/master/src/payload/collections"
    click CMSGlobals "https://github.com/cyr17/action-lab-website/tree/master/src/payload/globals"
    click Fields "https://github.com/cyr17/action-lab-website/tree/master/src/payload/fields"
    click Hooks "https://github.com/cyr17/action-lab-website/tree/master/src/payload/hooks"
    click Utilities "https://github.com/cyr17/action-lab-website/tree/master/src/payload/utilities"
    click API_Base "https://github.com/cyr17/action-lab-website/tree/master/src/app/(payload)/api"
    click API_Slug "https://github.com/cyr17/action-lab-website/blob/master/src/app/(payload)/api/[...slug]"
    click API_Playground "https://github.com/cyr17/action-lab-website/tree/master/src/app/(payload)/api/graphql-playground"
    click API_GraphQL "https://github.com/cyr17/action-lab-website/tree/master/src/app/(payload)/api/graphql"
    click AdminPanel "https://github.com/cyr17/action-lab-website/tree/master/src/app/(payload)/admin"

    %% Styles
    classDef client fill:#f9d,stroke:#333,stroke-width:2px;
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#fdb,stroke:#333,stroke-width:2px;
    classDef shared fill:#bfb,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#ffd,stroke:#333,stroke-width:2px;
    classDef api fill:#cfc,stroke:#333,stroke-width:2px;
```
