# m-u-c-k-a/transcendance architecture

> Architecture diagram of the GitHub repository m-u-c-k-a/transcendance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m-u-c-k-a/transcendance
- Repository: https://github.com/m-u-c-k-a/transcendance

## Overview

##### Project type and purpose
- This is a full-stack, multi-language web application built on Next.js (App Router).
- The “app” folder contains localized user-facing pages (auth, dashboard, game, profile, stats).
- The “server” folder implements a standalone Hapi (or similar) API service with JWT auth, Swagger docs, and Prisma ORM connectivity.
- Prisma manages a local SQLite database under prisma/data.
- A shared UI component library under “components/ui” and i18n assets under “lib/locales” support the frontend.

##### File structure
Top-level directories and their responsibilities:
- app/…: Next.js pages and layouts, organized per language placholder ([lang]). Uses server/client components (e.g. auth-client.tsx).
- components/: Reusable UI components and “components/ui” for primitives (buttons, dialogs, tables, etc.).
- hooks/: Custom React hooks (e.g. mobile detection).
- lib/: Shared utilities and i18n resources (dictionaries.ts, JSON locale files).
- prisma/: Database schema (schema.prisma), migrations, and test SQLite file.
- server/: Standalone API server code:
- config (environment variables)
- plugins (db.ts initializes Prisma, jwt.ts configures Hapi’s JWT plugin, swagger.ts sets up docs)
- routes/auth (login, registration endpoints)
- index.ts (bootstraps the server)
- middleware.ts: Next.js middleware (e.g. to detect locale, enforce auth).
- next.config.ts, postcss.config.mjs, eslint.config.mjs, tsconfig.json: build, lint, and framework configuration.

##### README for additional insights
- Confirms Create-Next-App bootstrap, use of next/font for optimized fonts.
- No built-in backend instructions, so the “server” folder runs as a separate process (e.g. `node server/index.js`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    User["User’s Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        NextApp["Next.js App Router"]:::frontend
        Middleware["Next.js Middleware\n(locale & auth)"]:::middleware
        Config["Next.js Configuration"]:::frontend
        subgraph "Pages & Layouts"
            direction TB
            Layouts["Global Layouts"]:::frontend
            Styles["Global Stylesheet"]:::frontend
            AuthPage["Auth Page"]:::frontend
            AuthClient["Auth Client"]:::frontend
            DashboardPage["Dashboard Page"]:::frontend
            DashboardClient["Dashboard Client"]:::frontend
            GamePage["Game Page"]:::frontend
            ProfilePage["Profile Page"]:::frontend
            StatsPage["Stats Page"]:::frontend
        end
        subgraph "UI Components"
            direction TB
            UIlib["Shared UI Component Library"]:::frontend
            subgraph "Reusable Components"
                Chat["Chat Component"]:::frontend
                LangSwitch["Language Switcher"]:::frontend
                ProfileDialog["Profile Edit Dialog"]:::frontend
                ThemeHandler["Theme Handler"]:::frontend
                ThemePersist["Theme Persistence"]:::frontend
                ThemeProvider["Theme Provider"]:::frontend
                ThemeToggle["Theme Toggle"]:::frontend
            end
        end
        subgraph "Hooks & i18n"
            direction TB
            Hooks["use-mobile Hook"]:::frontend
            I18n["i18n Utilities & Locale Files"]:::frontend
        end
        User -->|"requests pages"| NextApp
        NextApp -->|"/auth, /dashboard, /game, /profile, /stats"| Layouts
        Layouts -->|renders| AuthPage
        AuthPage -->|uses| AuthClient
        Layouts -->|renders| DashboardPage
        DashboardPage -->|uses| DashboardClient
        Layouts -->|renders| GamePage
        Layouts -->|renders| ProfilePage
        Layouts -->|renders| StatsPage
        NextApp -->|applies| Middleware
        NextApp -->|loads config| Config
        NextApp -->|imports| UIlib
        UIlib -->|includes| Chat
        UIlib -->|includes| LangSwitch
        UIlib -->|includes| ProfileDialog
        UIlib -->|includes| ThemeHandler
        UIlib -->|includes| ThemePersist
        UIlib -->|includes| ThemeProvider
        UIlib -->|includes| ThemeToggle
        NextApp -->|uses| Hooks
        NextApp -->|uses| I18n
    end

    %% Backend Layer
    subgraph "Backend API Server"
        direction TB
        APIServer["Hapi API Server"]:::backend
        ConfigAPI["Server Config"]:::backend
        PluginsDB["Prisma DB Plugin"]:::backend
        PluginsJWT["JWT Auth Plugin"]:::backend
        PluginsSwagger["Swagger Docs Plugin"]:::backend
        AuthRoutes["Auth Routes"]:::backend

        APIServer -->|boots| ConfigAPI
        APIServer -->|registers| PluginsDB
        APIServer -->|registers| PluginsJWT
        APIServer -->|registers| PluginsSwagger
        APIServer -->|mounts| AuthRoutes
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        PrismaSchema["Prisma Schema & Migrations"]:::db
        SQLiteDB["SQLite Database"]:::db
        PluginsDB -->|connects| PrismaSchema
        PrismaSchema -->|connects| SQLiteDB
    end

    %% Interactions
    NextApp -->|API calls /auth| APIServer
    AuthClient -->|fetch auth| APIServer
    User -->|direct API| APIServer
    PluginsSwagger -->|docs at /docs| User

    %% External Services
    subgraph "External Services"
        direction TB
        OAuth["Third-Party OAuth"]:::external
        Analytics["Analytics"]:::external
    end
    APIServer -->|optional auth| OAuth
    NextApp -->|logs| Analytics

    %% Click Events
    click NextApp "https://github.com/m-u-c-k-a/transcendance/tree/main/app/"
    click AuthPage "https://github.com/m-u-c-k-a/transcendance/blob/main/app/[lang]/auth/page.tsx"
    click AuthClient "https://github.com/m-u-c-k-a/transcendance/blob/main/app/[lang]/auth/auth-client.tsx"
    click DashboardPage "https://github.com/m-u-c-k-a/transcendance/blob/main/app/[lang]/dashboard/page.tsx"
    click DashboardClient "https://github.com/m-u-c-k-a/transcendance/blob/main/app/[lang]/dashboard/dashboard-client.tsx"
    click GamePage "https://github.com/m-u-c-k-a/transcendance/blob/main/app/[lang]/game/[mode]/page.tsx"
    click ProfilePage "https://github.com/m-u-c-k-a/transcendance/blob/main/app/[lang]/profile/[username]/page.tsx"
    click StatsPage "https://github.com/m-u-c-k-a/transcendance/blob/main/app/[lang]/stats/page.tsx"
    click Layouts "https://github.com/m-u-c-k-a/transcendance/blob/main/app/layout.tsx"
    click Styles "https://github.com/m-u-c-k-a/transcendance/blob/main/app/globals.css"
    click UIlib "https://github.com/m-u-c-k-a/transcendance/tree/main/components/ui/"
    click Chat "https://github.com/m-u-c-k-a/transcendance/blob/main/components/chat.tsx"
    click LangSwitch "https://github.com/m-u-c-k-a/transcendance/blob/main/components/language-switcher.tsx"
    click ProfileDialog "https://github.com/m-u-c-k-a/transcendance/blob/main/components/profile-edit-dialog.tsx"
    click ThemeHandler "https://github.com/m-u-c-k-a/transcendance/blob/main/components/theme-handler.tsx"
    click ThemePersist "https://github.com/m-u-c-k-a/transcendance/blob/main/components/theme-persistence.tsx"
    click ThemeProvider "https://github.com/m-u-c-k-a/transcendance/blob/main/components/theme-provider.tsx"
    click ThemeToggle "https://github.com/m-u-c-k-a/transcendance/blob/main/components/theme-toggle.tsx"
    click Hooks "https://github.com/m-u-c-k-a/transcendance/blob/main/hooks/use-mobile.ts"
    click I18n "https://github.com/m-u-c-k-a/transcendance/blob/main/lib/dictionaries.ts"
    click Middleware "https://github.com/m-u-c-k-a/transcendance/blob/main/middleware.ts"
    click Config "https://github.com/m-u-c-k-a/transcendance/blob/main/next.config.ts"
    click Config "https://github.com/m-u-c-k-a/transcendance/blob/main/postcss.config.mjs"
    click Config "https://github.com/m-u-c-k-a/transcendance/blob/main/eslint.config.mjs"
    click Config "https://github.com/m-u-c-k-a/transcendance/blob/main/tsconfig.json"
    click PrismaSchema "https://github.com/m-u-c-k-a/transcendance/blob/main/prisma/schema.prisma"
    click PrismaSchema "https://github.com/m-u-c-k-a/transcendance/tree/main/prisma/migrations/"
    click SQLiteDB "https://github.com/m-u-c-k-a/transcendance/blob/main/prisma/data/test.sqlite"
    click APIServer "https://github.com/m-u-c-k-a/transcendance/blob/main/server/index.ts"
    click ConfigAPI "https://github.com/m-u-c-k-a/transcendance/blob/main/server/config/env.ts"
    click PluginsDB "https://github.com/m-u-c-k-a/transcendance/blob/main/server/plugins/db.ts"
    click PluginsJWT "https://github.com/m-u-c-k-a/transcendance/blob/main/server/plugins/jwt.ts"
    click PluginsSwagger "https://github.com/m-u-c-k-a/transcendance/blob/main/server/plugins/swagger.ts"
    click AuthRoutes "https://github.com/m-u-c-k-a/transcendance/blob/main/server/routes/auth/index.ts"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef middleware fill:#F5B041,stroke:#B9770E,color:#1B2631
    classDef backend fill:#A9DFBF,stroke:#145A32,color:#1B2631
    classDef db fill:#D5DBDB,stroke:#566573,color:#1B2631
    classDef external fill:#D2B4DE,stroke:#78281F,color:#1B2631
```
