# asgerrud/chalkolate architecture

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

- Interactive diagram: https://gitdiagram.com/asgerrud/chalkolate
- Repository: https://github.com/asgerrud/chalkolate

## Overview

##### Main Components
- Frontend Client: Represented by the Next.js pages (found in src/pages), UI components (in src/components and src/components/ui), and styling (TailwindCSS configuration and global styles in src/globals.css). This layer handles the user interface and interactions.
- API Layer: Built using tRPC (evident from src/pages/api/trpc and the server API routers in src/server/api/routers). This provides the endpoints for data retrieval and manipulation.
- Server & Business Logic: Located in src/server (including authentication logic in src/server/auth.ts, db handling in src/server/db.ts, and various API routers that encapsulate business logic for accounts, challenges, schedules, and more).
- Database: Managed through Prisma (see prisma/schema.prisma, prisma/data.ts, prisma/seed.ts), indicating models, seeding, and migration logic.
- Authentication: Handled through NextAuth.js (found in src/pages/api/auth/[...nextauth].ts) providing authentication flows and secure access.

##### Relationships and Interactions
- The API Layer routes requests to the Server & Business Logic component which processes business rules (such as creating challenges, updating user profiles, or scheduling changes).
- An authentication flow where the client interacts with the NextAuth endpoint, which then verifies user data and sets up secure sessions that affect data access on both client and server.

##### Architectural Patterns and Design Principles
- Next.js Page-Based Routing: Show separate flows for page navigation (profile, settings, etc.) that are handled by dedicated pages.
- Separation of Concerns: UI components (presentation) are decoupled from business logic (server/api routers) and data management (Prisma models).
- API-Centric Design using tRPC: Emphasize how endpoints are type-safe and connect directly to the React UI.
- Modular Component-based approach: Use separate component folders (Layout, Navbar, challenge sections, etc.) to illustrate UI composition and reusability.
- Middleware/authentication: Clearly show that before API calls can mutate data, authentication is enforced via next-auth flows and utility functions like requireAuth.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Client Subgraph
    subgraph "Frontend Client"
        FE_Pages["Next.js Pages"]
        FE_Navbar["Navbar Component"]
        FE_Layout["Layout Component"]
        FE_UI["UI Components"]
        FE_Styles["Global Styles"]
        FE_Tailwind["Tailwind Config"]
    end

    %% API Layer Subgraph
    subgraph "API Layer"
        API_trpc["tRPC Endpoint"]
        API_Routers["API Routers"]
    end

    %% Server & Business Logic Subgraph
    subgraph "Server & Business Logic"
        Server_API["Server API Setup"]
        Server_Auth["Authentication Logic"]
        Server_DB["Database Connection"]
    end

    %% Authentication Subgraph
    subgraph "Authentication"
        NextAuth["NextAuth Service"]
        AuthMiddleware["Authentication Middleware"]
    end

    %% Database Subgraph
    subgraph "Database"
        Prisma["Prisma ORM"]
    end

    %% Connections from Frontend to API Layer
    FE_Pages -->|"tRPC_calls"| API_trpc
    FE_Navbar -->|"UI_interaction"| API_trpc
    FE_Layout -->|"UI_interaction"| API_trpc
    FE_UI -->|"UI_interaction"| API_trpc
    FE_Styles -->|"UI_interaction"| API_trpc
    FE_Tailwind -->|"UI_interaction"| API_trpc

    %% API Layer to Server & Business Logic
    API_trpc -->|"Routes_requests"| API_Routers
    API_Routers -->|"Executes_logic"| Server_API
    API_Routers -->|"Auth_check"| AuthMiddleware

    %% Server & Business Logic to Database
    Server_API -->|"CRUD_operations"| Server_DB
    Server_DB -->|"Persists_data"| Prisma

    %% Authentication Flow
    FE_Pages -->|"Auth_flow"| NextAuth
    NextAuth -->|"Validate_session"| AuthMiddleware
    AuthMiddleware -->|"Secure_access"| Server_Auth

    %% Class Definitions for Colors
    classDef frontend fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef api fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef server fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef auth fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef database fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    %% Apply Classes
    class FE_Pages,FE_Navbar,FE_Layout,FE_UI,FE_Styles,FE_Tailwind frontend;
    class API_trpc,API_Routers api;
    class Server_API,Server_Auth,Server_DB server;
    class NextAuth,AuthMiddleware auth;
    class Prisma database;

    %% Click Events for Frontend Components
    click FE_Pages "https://github.com/asgerrud/chalkolate/tree/main/src/pages"
    click FE_Navbar "https://github.com/asgerrud/chalkolate/blob/main/src/components/Navbar.tsx"
    click FE_Layout "https://github.com/asgerrud/chalkolate/blob/main/src/components/Layout.tsx"
    click FE_UI "https://github.com/asgerrud/chalkolate/blob/main/src/components/ui/button.tsx"
    click FE_Styles "https://github.com/asgerrud/chalkolate/blob/main/src/globals.css"
    click FE_Tailwind "https://github.com/asgerrud/chalkolate/blob/main/tailwind.config.js"

    %% Click Events for API Layer Components
    click API_trpc "https://github.com/asgerrud/chalkolate/blob/main/src/pages/api/trpc/[trpc].ts"
    click API_Routers "https://github.com/asgerrud/chalkolate/tree/main/src/server/api/routers"

    %% Click Events for Server & Business Logic Components
    click Server_API "https://github.com/asgerrud/chalkolate/blob/main/src/server/api/root.ts"
    click Server_Auth "https://github.com/asgerrud/chalkolate/blob/main/src/server/auth.ts"
    click Server_DB "https://github.com/asgerrud/chalkolate/blob/main/src/server/db.ts"

    %% Click Events for Authentication Components
    click NextAuth "https://github.com/asgerrud/chalkolate/blob/main/src/pages/api/auth/[...nextauth].ts"
    click AuthMiddleware "https://github.com/asgerrud/chalkolate/blob/main/src/lib/requireAuth.ts"

    %% Click Event for Database Component
    click Prisma "https://github.com/asgerrud/chalkolate/blob/main/prisma/schema.prisma"
```
