# hitbox38/the-grimoire architecture

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

- Interactive diagram: https://gitdiagram.com/hitbox38/the-grimoire
- Repository: https://github.com/hitbox38/the-grimoire

## Overview

##### Main components
- Frontend Views & Pages – All client-facing UI resides mostly under the “app” directory. This includes the landing page (app/page.tsx), login (app/login), sign-up, confirmation pages (app/auth/confirm), error handling (app/error/page.tsx) and additional reference pages (for example, within app/references such as bestiary, items, spells).
- API Endpoints – Under the “app/api” folder (with subdirectories like login and signup), you have server-side logic handling requests, which are likely responsible for authentication and data uploads.
- UI Components Library – The “components” directory holds reusable UI parts (e.g., Dashboard, StatsTable, and various UI elements inside components/ui). This represents the view layer that both pages and references use.
- Utility & Library Modules – The “lib” folder contains utility functions (like calculateStatModifier.ts) and “utils” holds modules for integrating external services (Firebase in utils/firebase and Supabase in utils/supabase).
- Configuration & Build Tools – Files like next.config.ts, tailwind.config.ts, tsconfig.json, and others manage build, configuration, and styling.

##### Relationships and interactions
- Frontend and API: The pages and actions within “app” (for login, signup, reference views) interact with API endpoints to process data. For example, app/api/login/route.ts handles login requests, while actions in app/login invoke these endpoints.
- Component Integration: The UI components from the “components” folder are composed within pages to render interactive elements. They likely receive data fetched from API endpoints or processed by libraries in “lib”.
- External Services: Utility modules in “utils/firebase” and “utils/supabase” represent the layers that abstract backend integrations. These modules are used within API endpoints or server-side logic to communicate with external databases or authentication services.
- Global Providers: Under “app/providers”, such as QueryProvider.tsx, global state or caching mechanisms (potentially using React Query or similar libraries) are set up to manage data across the application.
- Routing & Layout: The “app/layout.tsx” file sets up the common layout for pages, leveraging Next.js’s built-in routing and file-based code splitting.

##### Architectural patterns and design principles
- Separation of Concerns: The project clearly separates UI, API logic, external integrations, and utility functions.
- Component Reusability: With a dedicated UI component folder, the design emphasizes reusability for consistency across views.
- Modularization: Distinct directories for API endpoints, authentication flows, references, and configuration illustrate modular design.
- Full-stack Integration: By combining server-side API routes with client-side page rendering in Next.js, the project maintains a robust full-stack separation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Next.js Full-Stack Application"]:::config

    subgraph Frontend[Frontend: App Pages & Views]
        A1["Landing Page (app/page.tsx)"]:::frontend
        A2["Login Page (app/login/page.tsx)"]:::frontend
        subgraph References["Reference Pages"]
            R1["Bestiary (app/references/bestiary/page.tsx)"]:::frontend
            R2["Items (app/references/items/page.tsx)"]:::frontend
            R3["Spells (app/references/spells/page.tsx)"]:::frontend
        end
        A3["Auth Confirm (app/auth/confirm/route.ts)"]:::frontend
        A4["Error Page (app/error/page.tsx)"]:::frontend
    end

    subgraph Backend[Backend: API Endpoints]
        B1["Login API (app/api/login/route.ts)"]:::backend
        B2["Signup API (app/api/signup/route.ts)"]:::backend
    end

    subgraph UIComponents[UI Components Library]
        C1["Dashboard (components/Dashboard.tsx)"]:::comp
        C2["StatsTable (components/StatsTable.tsx)"]:::comp
        subgraph UIElements["UI Elements"]
            C3["Button (components/ui/button.tsx)"]:::comp
            C4["Card (components/ui/card.tsx)"]:::comp
        end
    end

    subgraph Integrations[Utilities & External Services]
        I1["Lib Utilities (lib)"]:::integration
        subgraph Firebase["Firebase Utilities"]
            F1["Client (utils/firebase/client.ts)"]:::integration
            F2["Config (utils/firebase/config.ts)"]:::integration
        end
        subgraph Supabase["Supabase Utilities"]
            S1["Client (utils/supabase/client.ts)"]:::integration
            S2["Middleware (utils/supabase/middleware.ts)"]:::integration
            S3["Server (utils/supabase/server.ts)"]:::integration
        end
    end

    subgraph Global[Global Providers & Layout]
        G1["Query Provider (app/providers/QueryProvider.tsx)"]:::provider
        G2["Layout & Global Styling (app/layout.tsx & app/globals.css)"]:::provider
    end

    subgraph Config[Configuration & Build Tools]
        CF1["Next Config (next.config.ts)"]:::config
        CF2["Tailwind Config (tailwind.config.ts)"]:::config
        CF3["TypeScript Config (tsconfig.json)"]:::config
        CF4["ESLint Config (.eslintrc.json)"]:::config
        CF5["PostCSS Config (postcss.config.mjs)"]:::config
    end

    %% Main system layer connections
    A --> A1
    A --> B1
    A --> C1
    A --> I1
    A --> G1
    A --> CF1

    %% Frontend interactions
    A2 -->|"submits"| B1
    %% Pages using UI components
    A1 -->|"composes"| C1
    A1 -->|"composes"| C2
    A1 -->|"composes"| C3
    A1 -->|"composes"| C4
    %% Global providers integrated in frontend
    A1 -->|"wrappedBy"| G1
    A1 -->|"includes"| G2

    %% API endpoints interactions with external services
    B1 -->|"uses"| I1
    B2 -->|"uses"| I1
    B1 -->|"calls"| F1
    B1 -->|"calls"| F2
    B2 -->|"calls"| S1
    B2 -->|"calls"| S2
    B2 -->|"calls"| S3

    %% Class definitions for styling
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef comp fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef integration fill:#A3E4D7,stroke:#1ABC9C,stroke-width:2px;
    classDef provider fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef config fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;

click A1 "https://github.com/hitbox38/the-grimoire/blob/main/app/page.tsx"
click A2 "https://github.com/hitbox38/the-grimoire/blob/main/app/login/page.tsx"
click R1 "https://github.com/hitbox38/the-grimoire/blob/main/app/references/bestiary/page.tsx"
click R2 "https://github.com/hitbox38/the-grimoire/blob/main/app/references/items/page.tsx"
click R3 "https://github.com/hitbox38/the-grimoire/blob/main/app/references/spells/page.tsx"
click A3 "https://github.com/hitbox38/the-grimoire/blob/main/app/auth/confirm/route.ts"
click A4 "https://github.com/hitbox38/the-grimoire/blob/main/app/error/page.tsx"
click B1 "https://github.com/hitbox38/the-grimoire/blob/main/app/api/login/route.ts"
click B2 "https://github.com/hitbox38/the-grimoire/blob/main/app/api/signup/route.ts"
click C1 "https://github.com/hitbox38/the-grimoire/blob/main/components/Dashboard.tsx"
click C2 "https://github.com/hitbox38/the-grimoire/blob/main/components/StatsTable.tsx"
click C3 "https://github.com/hitbox38/the-grimoire/blob/main/components/ui/button.tsx"
click C4 "https://github.com/hitbox38/the-grimoire/blob/main/components/ui/card.tsx"
click I1 "https://github.com/hitbox38/the-grimoire/tree/main/lib"
click F1 "https://github.com/hitbox38/the-grimoire/blob/main/utils/firebase/client.ts"
click F2 "https://github.com/hitbox38/the-grimoire/blob/main/utils/firebase/config.ts"
click S1 "https://github.com/hitbox38/the-grimoire/blob/main/utils/supabase/client.ts"
click S2 "https://github.com/hitbox38/the-grimoire/blob/main/utils/supabase/middleware.ts"
click S3 "https://github.com/hitbox38/the-grimoire/blob/main/utils/supabase/server.ts"
click G1 "https://github.com/hitbox38/the-grimoire/blob/main/app/providers/QueryProvider.tsx"
click G2 "https://github.com/hitbox38/the-grimoire/blob/main/app/layout.tsx"
click CF1 "https://github.com/hitbox38/the-grimoire/blob/main/next.config.ts"
click CF2 "https://github.com/hitbox38/the-grimoire/blob/main/tailwind.config.ts"
click CF3 "https://github.com/hitbox38/the-grimoire/blob/main/tsconfig.json"
click CF4 "https://github.com/hitbox38/the-grimoire/blob/main/.eslintrc.json"
click CF5 "https://github.com/hitbox38/the-grimoire/blob/main/postcss.config.mjs"
```
