# jaedanpersaud12/spotr architecture

> Architecture diagram of the GitHub repository jaedanpersaud12/spotr, 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/jaedanpersaud12/spotr
- Repository: https://github.com/jaedanpersaud12/spotr

## Overview

##### Main Components
- Frontend: Represented by the Next.js application. The “src/app” folder contains the page components (e.g., onboarding, dashboard, business pages) and shared components in “src/components”. Also indicate UI components (from “src/components/ui”) that form the building blocks of the visual interface.
- API Layer: Several API endpoints exist under “src/app/api” (with subdirectories for tRPC endpoints and webhooks). The TRPC integration has both client-side files (in “src/trpc”) and server routes (in “src/server/api/routers”).
- Business Logic and Server Side Operations: The “src/server” directory holds the API entry point (“root.ts”), the routers for business, roles, services, and users, along with queries, mutations, and database helper code.
- Database: Two representations are visible:
- Drizzle ORM is configured via “drizzle.config.ts”, with migration SQL files in the “drizzle” folder and schema definitions spread across “src/server/db” and “src/server/db/schema”.
- Snapshots of the database state and a meta journal are maintained in “drizzle/meta”.
- Configuration and Utility Layers: Look at configuration files (e.g., .env.example, next.config.js, tailwind.config.ts, tsconfig.json) and utility functions (e.g., “src/lib/utils.ts”, “src/utils/roles.ts”) that support the application’s setup and operations.

##### Relationships and Data Flow
- The user interacts with the Frontend (Next.js pages and components), which then makes API calls (via tRPC) to the Backend.
- The API layer in “src/app/api” and “src/server/api” handles incoming requests, processes business logic (using queries and mutations), and communicates with the Database through the ORM (Drizzle).
- User → Frontend UI → API Layer (tRPC calls, webhooks) → Business Logic → Database.

##### Architectural Patterns and Important Technologies
- MVC/MV* Pattern: Although Next.js enforces its own file-based routing, observe that your “pages” (or app routes) act as “views” and the API routes plus business logic constitute the “controller” layer.
- API Gateway Pattern: tRPC serves as the bridge for client–server communication.
- ORM and Migration Pattern: Drizzle ORM is used along with SQL migration files to manage the database schema and versioning.

- Use clear, descriptive labels for each component (e.g., “Next.js Frontend – Pages & Components”, “tRPC API Endpoints”, “Business Logic & Routers”, “Drizzle ORM & Database Migrations”).
- Internal dependencies: The configuration files like “next.config.js”, “tailwind.config.ts”, and environment variable examples (.env.example) might be drawn externally, indicating they are used across components.

##### Additional Elements to Not Overlook
- That database migrations and snapshot files (under “drizzle” and “drizzle/meta”) are represented as part of the Database layer to reflect schema evolution.
- Separation in responsibilities:
- Frontend: UI/UX, routing, and component composition.
- API and Business Logic: Type-safe communication via tRPC, encapsulated business operations via routers and controllers.
- Database: Persistent storage managed through Drizzle migrations and schema definitions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    U("User"):::external

    %% Frontend Layer
    subgraph "Frontend - Next.js Pages & Components"
        FE_Pages("Pages (Routing)"):::frontend
        FE_Components("Shared Components"):::frontend
        FE_UI("UI Components"):::frontend
        TRPC_Client("tRPC Client Integration"):::frontend
    end

    %% API Layer
    subgraph "API Layer"
        API_Endpoint("tRPC API Endpoint"):::api
        API_Webhooks("Webhooks Endpoint"):::api
    end

    %% Business Logic & Server Layer
    subgraph "Business Logic & Server"
        BL_Root("API Entry & Routers"):::business
        BL_Queries("Queries"):::business
        BL_Mutations("Mutations"):::business
    end

    %% Database Layer
    subgraph "Database - Drizzle ORM & Migrations"
        DB_Config("Drizzle ORM Config"):::database
        DB_Migrations("Migration Files"):::database
        DB_Snapshots("Database Snapshots"):::database
        DB_Schema("Schema Definitions"):::database
    end

    %% Configuration & Utilities
    subgraph "Configurations & Utilities"
        Config_Env("Environment Config"):::config
        Config_Next("Next Config"):::config
        Config_Tailwind("Tailwind Config"):::config
        Config_TS("TS Config"):::config
        Utils_Func("Utility Functions"):::config
        Utils_Roles("Roles Utility"):::config
    end

    %% Relationships
    U -->|"Uses"| FE_Pages
    FE_Pages -->|"APIcall"| TRPC_Client
    TRPC_Client -->|"calls"| API_Endpoint
    API_Endpoint -->|"forwards"| BL_Root
    API_Webhooks -->|"notifies"| BL_Root
    BL_Root -->|"executes"| BL_Queries
    BL_Root -->|"executes"| BL_Mutations
    BL_Queries -->|"queries"| DB_Config
    BL_Mutations -->|"updates"| DB_Config
    DB_Config -->|"applies"| DB_Migrations
    DB_Migrations -->|"defines"| DB_Schema
    DB_Config -->|"records"| DB_Snapshots

    %% Configurations dependencies (dashed arrows)
    Config_Env ---|"config"| FE_Pages
    Config_Next ---|"config"| FE_Pages
    Config_Tailwind ---|"config"| FE_Pages
    Config_TS ---|"config"| BL_Root
    Utils_Func ---|"utilized"| BL_Root
    Utils_Roles ---|"utilized"| BL_Root

    %% Additional integration arrow for tRPC type-safety
    TRPC_Client ---|"type-safe integration"| API_Endpoint

    %% Click Events - Frontend
    click FE_Pages "https://github.com/jaedanpersaud12/spotr/tree/main/src/app"
    click FE_Components "https://github.com/jaedanpersaud12/spotr/tree/main/src/components"
    click FE_UI "https://github.com/jaedanpersaud12/spotr/tree/main/src/components/ui"
    click TRPC_Client "https://github.com/jaedanpersaud12/spotr/blob/main/src/trpc/react.tsx"

    %% Click Events - API Layer
    click API_Endpoint "https://github.com/jaedanpersaud12/spotr/blob/main/src/app/api/trpc/[trpc]/route.ts"
    click API_Webhooks "https://github.com/jaedanpersaud12/spotr/blob/main/src/app/api/webhooks/route.ts"

    %% Click Events - Business Logic & Server
    click BL_Root "https://github.com/jaedanpersaud12/spotr/blob/main/src/server/api/root.ts"
    click BL_Queries "https://github.com/jaedanpersaud12/spotr/blob/main/src/server/queries.ts"
    click BL_Mutations "https://github.com/jaedanpersaud12/spotr/blob/main/src/server/mutations.ts"
    %% Assuming routers are bundled in the directory
    click BL_Root "https://github.com/jaedanpersaud12/spotr/tree/main/src/server/api/routers"

    %% Click Events - Database Layer
    click DB_Config "https://github.com/jaedanpersaud12/spotr/blob/main/drizzle.config.ts"
    click DB_Migrations "https://github.com/jaedanpersaud12/spotr/tree/main/drizzle"
    click DB_Snapshots "https://github.com/jaedanpersaud12/spotr/tree/main/drizzle/meta"
    click DB_Schema "https://github.com/jaedanpersaud12/spotr/tree/main/src/server/db/schema"

    %% Click Events - Configurations & Utilities
    click Config_Env "https://github.com/jaedanpersaud12/spotr/blob/main/.env.example"
    click Config_Next "https://github.com/jaedanpersaud12/spotr/blob/main/next.config.js"
    click Config_Tailwind "https://github.com/jaedanpersaud12/spotr/blob/main/tailwind.config.ts"
    click Config_TS "https://github.com/jaedanpersaud12/spotr/blob/main/tsconfig.json"
    click Utils_Func "https://github.com/jaedanpersaud12/spotr/blob/main/src/lib/utils.ts"
    click Utils_Roles "https://github.com/jaedanpersaud12/spotr/blob/main/src/utils/roles.ts"

    %% Styles
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef business fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#e2cfe3,stroke:#0c5460,stroke-width:2px;
    classDef config fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
