# planetscale/beam architecture

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

- Interactive diagram: https://gitdiagram.com/planetscale/beam
- Repository: https://github.com/planetscale/beam

## Overview

##### Main Components
- Frontend: Represented by the Next.js pages (located under the pages/ directory) and UI components (in the components/ folder). These include the core public pages (home, post details, profile, sign-in) and controls that bring the Markdown editor, image handling, and interactive elements like buttons and dialogs together.
- Backend/API: Capture the API endpoints and server-side routing. This includes the API routes in pages/api (e.g., authentication with NextAuth.js, Cloudinary sign, and trpc integration) as well as the server/ folder which contains the context and routers that handle business logic (comment, post, user operations).
- Business Logic & Services Layer: The lib/ folder holds key utility functions and service integrations (e.g., auth, prisma, cloudinary, slack, and tRPC). This layer encapsulates much of the application logic.
- Database: Indicate the connection with a PlanetScale database managed via Prisma (prisma/schema.prisma), with additional seed data and schema definitions under .pscale/seed-data.
- External Services: Include integrations with Cloudinary (for image uploads), Slack (for notifications), and the authentication providers (GitHub/Okta via NextAuth.js).

##### Relationships and Interactions
- Backend’s interaction with the Database using Prisma, outlining how requests for data (user posts, comments) are pushed/pulled from PlanetScale.
- Authentication flows where NextAuth.js manages logins and callbacks.
- Image uploads which route to Cloudinary.
- Slack notifications being triggered after certain events like new posts.
- That the business logic (server/routers and lib/ functions) serves as the intermediary between the API and the database/external integrations.

##### Architectural Patterns and Design Principles
- That the project follows a typical full-stack separation: a React-based frontend with a Node/Next.js backend.
- Modular, component-based structure in both UI (components/) and server routing (server/routers).
- Stress the use of environment-specific configuration (separated in env/ and .env files) to properly configure services like PlanetScale, Cloudinary, and Slack.
- That tRPC is used to create a typesafe API layer between the frontend and backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FN1["Next.js Pages"]:::frontend
        FN2["UI Components"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        AP1["Auth Endpoint"]:::backend
        AP2["Cloudinary Sign Endpoint"]:::backend
        AP3["tRPC Endpoint"]:::backend
        BS["Server-Side Business Logic & Routing"]:::backend
    end

    %% Business Logic & Services Layer
    subgraph "Business Logic & Services Layer"
        BL["Service Integrations (lib)"]:::logic
    end

    %% Database Layer
    subgraph "Database Layer"
        DB1["Prisma ORM Schema"]:::database
        DB2["PlanetScale Seed Data"]:::database
    end

    %% External Services Layer
    subgraph "External Services Layer"
        EX1["Cloudinary Integration"]:::external
        EX2["Slack Notifications"]:::external
        EX3["Authentication Providers"]:::external
    end

    %% Legend (for color codes)
    subgraph "Legend"
        L1["Frontend: Light Green"]:::frontend
        L2["Backend/API: Light Blue"]:::backend
        L3["Business Logic: Light Orange"]:::logic
        L4["Database: Light Yellow"]:::database
        L5["External Services: Light Red"]:::external
    end

    %% Connections
    FN1 -->|"HTTPcalls"| AP1
    FN1 -->|"tRPCcalls"| AP3
    FN2 -->|"Imageupload"| AP2

    AP1 -->|"Authflow"| EX3
    AP1 -->|"ProcessReq"| BS
    AP2 -->|"ProcessUpload"| BS
    AP3 -->|"DataFetch"| BS

    BS -->|"HandleLogic"| BL

    BL -->|"DBoperations"| DB1
    BL -->|"SeedOps"| DB2
    BL -->|"NotifyEvents"| EX2
    BL -->|"UploadOps"| EX1

    %% Click Events
    click FN1 "https://github.com/planetscale/beam/tree/main/pages/"
    click FN2 "https://github.com/planetscale/beam/tree/main/components/"
    click AP1 "https://github.com/planetscale/beam/blob/main/pages/api/auth/[...nextauth].ts"
    click AP2 "https://github.com/planetscale/beam/blob/main/pages/api/sign-cloudinary.ts"
    click AP3 "https://github.com/planetscale/beam/blob/main/pages/api/trpc/[trpc].ts"
    click BS "https://github.com/planetscale/beam/tree/main/server/"
    click BL "https://github.com/planetscale/beam/tree/main/lib/"
    click DB1 "https://github.com/planetscale/beam/blob/main/prisma/schema.prisma"
    click DB2 "https://github.com/planetscale/beam/tree/main/.pscale/seed-data/"
    click EX1 "https://github.com/planetscale/beam/blob/main/lib/cloudinary.ts"
    click EX2 "https://github.com/planetscale/beam/blob/main/lib/slack.ts"
    click EX3 "https://github.com/planetscale/beam/blob/main/pages/api/auth/[...nextauth].ts"

    %% Styles
    classDef frontend fill:#aeeaae,stroke:#333,stroke-width:2px;
    classDef backend fill:#aec6ff,stroke:#333,stroke-width:2px;
    classDef logic fill:#ffdfba,stroke:#333,stroke-width:2px;
    classDef database fill:#fdfd96,stroke:#333,stroke-width:2px;
    classDef external fill:#ffb3ba,stroke:#333,stroke-width:2px;
```
