# jonp-h/tillerquest architecture

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

- Interactive diagram: https://gitdiagram.com/jonp-h/tillerquest
- Repository: https://github.com/jonp-h/tillerquest

## Overview

##### Project type and purpose
- TillerQuest is a full-stack web application: a browser-based RPG remake (“Heimdallsquest”) built with a Next.js frontend (app-router), a standalone Node/TypeScript backend, and a PostgreSQL database.

##### File structure
- Top level:
- frontend/ – Next.js app using React, SSR, CSR, API routes for Auth.js, Prisma client, public assets (WASM, themes, textures).
- backend/ – Node/TypeScript service (src/index.ts), Express-style routes or custom handlers, middleware, Prisma client, DB seeding/generation scripts.
- backend/db/docker – Docker Compose for local PostgreSQL.
- prisma/ in both frontend and backend – migrations and schema definitions, shared database.
- Patterns:
- Clear separation of UI (Next.js pages/components) vs. business logic/authoritative API (backend).
- App-router nested directories under frontend/app/(protected) for RBAC.
- Middleware folders in both layers (auth.ts in frontend for SSR, auth.config in backend).
- Shared lib modules for logging, error handling, DB connections.

##### README for additional insights
- Confirms Next.js app-router usage, SSR preference, architecture conventions (components colocated under “_components”), TypeScript interfaces, Tailwind dark-mode style, external dependencies.

##### Elements
- Frontend (blue rectangles)
- Backend (green rectangles)
- Annotations for major flows (e.g., “User Login Flow”, “Game Data Fetch”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser Layer"
        Browser["User's Browser"]:::frontend
    end

    %% Frontend Layer
    subgraph "Next.js Frontend Server"
        direction TB
        NextFrontend["Next.js Frontend"]:::frontend
        SSRPages["SSR Pages & App Router"]:::frontend
        ClientComponents["Client Components"]:::frontend
        Layout["Layout & Global Styles"]:::frontend
        NextAuthRoute["NextAuth API Route"]:::frontend
        AuthConfigFS["Auth Config & Helpers"]:::frontend
        PrismaFrontend["Prisma Client & Migrations"]:::frontend
        ZodFrontend["Zod Validators"]:::frontend
        D3Components["D3 Visualizations"]:::frontend
        LoggerFront["Winston Logger"]:::frontend
        DiscordHelper["Discord Webhook Helper"]:::frontend

        NextFrontend --> SSRPages
        NextFrontend --> ClientComponents
        NextFrontend --> Layout
        NextFrontend --> NextAuthRoute
        NextFrontend --> AuthConfigFS
        NextFrontend --> PrismaFrontend
        NextFrontend --> ZodFrontend
        NextFrontend --> D3Components
        NextFrontend --> LoggerFront
        NextFrontend --> DiscordHelper
    end

    %% Backend Layer
    subgraph "Node.js Backend Service"
        direction TB
        NodeBackend["Node.js Backend"]:::backend
        APIEndpoints["HTTP/API Endpoints"]:::backend
        Middleware["Auth & Validation Middleware"]:::backend
        PrismaBackend["Prisma Client & Migrations"]:::backend
        ZodBackend["Zod Validators"]:::backend
        SeedScripts["DB Seeding & Reset Scripts"]:::backend

        NodeBackend --> APIEndpoints
        NodeBackend --> Middleware
        NodeBackend --> PrismaBackend
        NodeBackend --> ZodBackend
        NodeBackend --> SeedScripts
    end

    %% Database
    subgraph "Database"
        Postgres["PostgreSQL"]:::db
    end

    %% External Services
    subgraph "External Services"
        GitHub["GitHub OAuth Provider"]:::external
        Discord["Discord Webhook"]:::external
    end

    %% Connections
    Browser <-->|"HTTP(S) Requests"| NextFrontend
    NextFrontend -->|"OAuth Flow"| GitHub
    NextFrontend -->|"Prisma Session Storage"| Postgres
    NextFrontend -->|"REST API Calls"| NodeBackend
    NodeBackend -->|"Prisma Queries"| Postgres
    NodeBackend -->|"Webhook Calls"| Discord

    %% Click Events - Frontend
    click NextFrontend "https://github.com/jonp-h/tillerquest/tree/main/frontend/"
    click SSRPages "https://github.com/jonp-h/tillerquest/tree/main/frontend/app/"
    click ClientComponents "https://github.com/jonp-h/tillerquest/tree/main/frontend/app/**/_components"
    click Layout "https://github.com/jonp-h/tillerquest/blob/main/frontend/app/layout.tsx"
    click Layout "https://github.com/jonp-h/tillerquest/blob/main/frontend/app/globals.css"
    click NextAuthRoute "https://github.com/jonp-h/tillerquest/blob/main/frontend/app/api/auth/[...nextauth]/route.ts"
    click AuthConfigFS "https://github.com/jonp-h/tillerquest/blob/main/frontend/auth.ts"
    click AuthConfigFS "https://github.com/jonp-h/tillerquest/blob/main/frontend/auth.config.ts"
    click PrismaFrontend "https://github.com/jonp-h/tillerquest/blob/main/frontend/prisma/schema.prisma"
    click PrismaFrontend "https://github.com/jonp-h/tillerquest/tree/main/frontend/prisma/migrations/"
    click ZodFrontend "https://github.com/jonp-h/tillerquest/blob/main/frontend/data/validators/validators.ts"
    click ZodFrontend "https://github.com/jonp-h/tillerquest/blob/main/frontend/data/validators/userUpdateValidation.ts"
    click ZodFrontend "https://github.com/jonp-h/tillerquest/blob/main/frontend/data/validators/secretValidation.ts"
    click D3Components "https://github.com/jonp-h/tillerquest/blob/main/frontend/app/(protected)/abilities/_components/AbilityTree.tsx"
    click LoggerFront "https://github.com/jonp-h/tillerquest/blob/main/frontend/lib/logger.ts"
    click DiscordHelper "https://github.com/jonp-h/tillerquest/blob/main/frontend/lib/discord.ts"

    %% Click Events - Backend
    click NodeBackend "https://github.com/jonp-h/tillerquest/blob/main/backend/src/index.ts"
    click APIEndpoints "https://github.com/jonp-h/tillerquest/blob/main/backend/src/data/*.ts"
    click APIEndpoints "https://github.com/jonp-h/tillerquest/blob/main/backend/src/gameSettings.ts"
    click Middleware "https://github.com/jonp-h/tillerquest/blob/main/backend/src/middleware/auth.ts"
    click Middleware "https://github.com/jonp-h/tillerquest/blob/main/backend/src/middleware/auth.config.ts"
    click PrismaBackend "https://github.com/jonp-h/tillerquest/blob/main/backend/prisma/schema.prisma"
    click PrismaBackend "https://github.com/jonp-h/tillerquest/tree/main/backend/prisma/migrations/"
    click ZodBackend "https://github.com/jonp-h/tillerquest/blob/main/backend/src/data/validators.ts"
    click SeedScripts "https://github.com/jonp-h/tillerquest/blob/main/backend/db/generate.js"
    click SeedScripts "https://github.com/jonp-h/tillerquest/blob/main/backend/db/reset.js"
    click SeedScripts "https://github.com/jonp-h/tillerquest/blob/main/backend/db/abilities.js"
    click SeedScripts "https://github.com/jonp-h/tillerquest/blob/main/backend/db/users.js"
    click SeedScripts "https://github.com/jonp-h/tillerquest/blob/main/backend/db/docker/docker-compose.yml"
    click .husky "https://github.com/jonp-h/tillerquest/tree/main/ .husky/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#D0FFD8,stroke:#28a745,color:#155724;
    classDef db fill:#FFF2CC,stroke:#c49000,color:#c49000;
    classDef external fill:#F0E0FF,stroke:#6f42c1,color:#6f42c1;
```
