# lithiumox-codam/transcendence architecture

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

- Interactive diagram: https://gitdiagram.com/lithiumox-codam/transcendence
- Repository: https://github.com/lithiumox-codam/transcendence

## Overview

##### Project type and purpose
- This is a turborepo-based full-stack real-time multiplayer “Transcendence” application.
- The frontend is a SvelteKit app (apps/frontend) providing UI, internationalization, routing, and TRPC client hooks.
- The backend is a Node/TypeScript server (apps/backend) using tRPC routers, matchmaking, event emitters, game logic, and a relational database via Drizzle ORM.
- Shared packages implement cross-cutting concerns: authentication, database schema/ORM, game logic, and tRPC utilities.

##### File structure
- Top-level directories:
- apps/frontend – SvelteKit code, components, routes, TRPC client, i18n
- apps/backend – tRPC server entrypoint, router mounting
- packages/auth – OAuth flows, session management
- packages/database – Drizzle configuration, schemas, types, data access utilities
- packages/game – core game logic, rules, state transitions
- packages/trpc – tRPC router definitions (auth, chat, game, stats, GDPR, friends, user), typed emitter, matchmaking, root router
- packages/tsconfig – shared TypeScript configs
- turbo.json, pnpm-workspace.yaml – monorepo build orchestrators
- Configuration files for build, linting, formatting, VSCode workspace all live at the root.

##### README
- Confirms a turborepo starter with two SvelteKit apps and shared libraries.

##### Main components
a. Frontend
- SvelteKit App (apps/frontend)
- TRPC client layer (HTTP + WebSocket transport)
- UI components (Chat, Game board, Stats, Authentication flows)
- i18n subsystem
b. Backend
- Node.js tRPC server (apps/backend  packages/trpc)
- tRPC routers (auth, chat, game, friends, stats, GDPR, user)
- Event emitter / matchmaking engine (packages/trpc/src/events, matchmaking.ts)
- Game logic module (packages/game)
- Auth module (packages/auth)
- Database access layer (Drizzle ORM in packages/database)
c. Infrastructure
- Relational Database (e.g., PostgreSQL via Drizzle)
- External OAuth providers (Google, etc.)
- Monorepo toolchain (pnpm, Turborepo)
d. CI/CD and Dev Tools
- GitHub workflows (.github)
- VS Code workspace config
- Build orchestrator (turbo.json)

##### Relationships and interactions
- The SvelteKit frontend issues TRPC calls over HTTP/WebSockets to the Node tRPC server.
- tRPC resolvers invoke:
- Auth module for sign-in, JWT/session management, OAuth callback flows
- Database module for CRUD operations, schema enforcement
- Game module for game state updates, match creation
- Event emitter for broadcasting chat messages, game events to subscribed clients
- The backend persists data to the database and integrates with external OAuth endpoints.
- Shared packages are imported by both frontend (tsconfig, types) and backend (business logic).

##### Architectural patterns and principles
- Monorepo with modular packages for separation of concerns and code reuse.
- Client-server separation with strong typing via tRPC.
- Event-driven design for real-time features using typed emitters and WebSockets.
- Layered architecture: API layer (tRPC) → domain layer (game, auth, chat) → data layer (Drizzle).
- Feature-based routing in SvelteKit for auth, protected routes, demos, privacy pages.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client" 
        direction TB
        SK["SvelteKit App"]:::frontend
        TRPCClient["TRPC Client Layer"]:::frontend
        UI["UI Components"]:::frontend
        I18n["i18n Subsystem"]:::frontend
    end

    %% Server Layer
    subgraph "Server"
        direction TB
        Entry["tRPC Server Entrypoint"]:::backend
        subgraph "tRPC Routers"
            direction TB
            AuthRouter["Auth Router"]:::backend
            ChatRouter["Chat Router"]:::backend
            GameRouter["Game Router"]:::backend
            FriendsRouter["Friends Router"]:::backend
            StatsRouter["Stats Router"]:::backend
            GDPRRouter["GDPR Router"]:::backend
            UserRouter["User Router"]:::backend
            BlockRouter["Block Router"]:::backend
            RootRouter["Root Router"]:::backend
        end
        Events["Typed Event Emitter"]:::backend
        EventsDef["Event Definitions"]:::backend
        Matchmaking["Matchmaking Engine"]:::backend
        GameLogic["Game Logic Module"]:::backend
        AuthMod["Authentication Module"]:::backend
        DBLayer["Database Access Layer"]:::backend
    end

    %% Shared Packages
    subgraph "Shared Libraries"
        direction TB
        TSConfig["TypeScript Configs"]:::shared
    end

    %% External & Infrastructure
    subgraph "External & Infra"
        direction TB
        DB["Relational Database"]:::external
        OAuth["OAuth Providers"]:::external
        Monorepo["Monorepo Tooling"]:::external
        CI["CI/CD & Dev Tools"]:::external
    end

    %% Connections
    SK -->|uses| TRPCClient
    TRPCClient -->|HTTP/WebSocket| Entry
    Entry -->|registers routers| RootRouter
    RootRouter --> AuthRouter
    RootRouter --> ChatRouter
    RootRouter --> GameRouter
    RootRouter --> FriendsRouter
    RootRouter --> StatsRouter
    RootRouter --> GDPRRouter
    RootRouter --> UserRouter
    RootRouter --> BlockRouter
    AuthRouter --> AuthMod
    ChatRouter --> Events
    GameRouter --> GameLogic
    GameRouter --> Matchmaking
    Events --> EventsDef
    Matchmaking --> GameLogic
    AuthMod -->|OAuth flows| OAuth
    AuthMod --> DBLayer
    DBLayer --> DB
    Events -->|push events| TRPCClient
    SK -->|imports types| TSConfig
    Entry -->|imports| TSConfig
    Monorepo --> SK
    Monorepo --> Entry
    CI --> Monorepo

    %% Click Events
    click SK "https://github.com/lithiumox-codam/transcendence/tree/main/apps/frontend"
    click TRPCClient "https://github.com/lithiumox-codam/transcendence/blob/main/apps/frontend/src/lib/trpc.ts"
    click UI "https://github.com/lithiumox-codam/transcendence/tree/main/apps/frontend/src/lib/components"
    click I18n "https://github.com/lithiumox-codam/transcendence/blob/main/apps/frontend/src/lib/i18n.ts"
    click Entry "https://github.com/lithiumox-codam/transcendence/blob/main/apps/backend/src/index.ts"
    click AuthRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/router/auth.ts"
    click ChatRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/router/chat.ts"
    click GameRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/router/game.ts"
    click FriendsRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/router/friends.ts"
    click StatsRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/router/stats.ts"
    click GDPRRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/router/gdpr.ts"
    click UserRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/router/user.ts"
    click BlockRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/router/block.ts"
    click RootRouter "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/root.ts"
    click Events "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/events/typedEmitter.ts"
    click EventsDef "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/events/index.ts"
    click Matchmaking "https://github.com/lithiumox-codam/transcendence/blob/main/packages/trpc/src/matchmaking.ts"
    click GameLogic "https://github.com/lithiumox-codam/transcendence/blob/main/packages/game/src/index.ts"
    click AuthMod "https://github.com/lithiumox-codam/transcendence/blob/main/packages/auth/src/index.ts"
    click DBLayer "https://github.com/lithiumox-codam/transcendence/blob/main/packages/database/src/database.ts"
    click Monorepo "https://github.com/lithiumox-codam/transcendence/blob/main/turbo.json"
    click Monorepo "https://github.com/lithiumox-codam/transcendence/blob/main/pnpm-workspace.yaml"
    click TSConfig "https://github.com/lithiumox-codam/transcendence/blob/main/packages/tsconfig/base.json"
    click CI "https://github.com/lithiumox-codam/transcendence/tree/main/.github/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E6F4EA,stroke:#22863A,color:#22863A
    classDef shared fill:#FFF5B1,stroke:#D4A72C,color:#735C0F
    classDef external fill:#F3F4F6,stroke:#6A737D,color:#6A737D
```
