# cktang88/dungeon-game architecture

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

- Interactive diagram: https://gitdiagram.com/cktang88/dungeon-game
- Repository: https://github.com/cktang88/dungeon-game

## Overview

##### Project type and purpose
- This is a full-stack, LLM-driven, real-time text-based dungeon crawler with a React/Vite/Tailwind frontend (“game-client”) and a Node.js/TypeScript backend (“game-server”).
- The backend hosts game logic, procedural generation modules, state management, and connectors to LLM services (OpenAI, Gemini). The frontend renders UI (map, chatbox, inventory, stats) and communicates with the server over WebSockets.

##### File structure
Top level:
- ARCHITECTURE.md, README.md, examples/ (prompt snippets), todos.md
- game-client/ : React + Vite + Tailwind project
- game-server/ : TypeScript Node.js project
game-client structure:
- src/components/… (UI layout, chatbox, map, inventory, stats)
- src/lib/api.ts (HTTP/REST), src/lib/socket.ts (WebSocket client helper)
- package.json, vite.config.ts, postcss.config.js, tailwind.config.js
game-server structure:
- src/index.ts (entrypoint)
- src/game/… (actions.ts, state.ts, generation modules)
- src/lib/openai.ts, src/lib/gemini.ts (LLM connectors)
- data/… JSON/text files for environments, items, monsters, weapons, potions
- .env.example for API keys

##### README insights
- Describes room-by-room gameplay, D&D-style stats, LLM involvement in combat, puzzles, narration
- Future TODOs: memory storage (Zep/Mem0), BAML integration

##### Detail without over-splitting
- Essential modules (generation, state, LLM integration)
- Avoid drawing every single React component; instead, group UI components under “UI Layer”
- Flow of data—from player input in the browser → LLM and domain logic on server → rendering—remains crystal clear

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (game-client)"
        classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
        FEEntrypoint["main.tsx"]:::frontend
        subgraph "UI Layer"
            UILayer["src/components/"]:::frontend
            UIPrimitives["src/components/ui/"]:::frontend
        end
        APIClient["src/lib/api.ts"]:::frontend
        SocketClient["src/lib/socket.ts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (game-server)"
        classDef backend fill:#D0F5D0,stroke:#333,stroke-width:1px
        BEEntrypoint["src/index.ts"]:::backend
        Actions["src/game/actions.ts"]:::backend
        State["src/game/state.ts"]:::backend
        subgraph "Generation Modules"
            MapGen["src/game/generation/mapGen.ts"]:::backend
            MonsterGen["src/game/generation/monsterGen.ts"]:::backend
            ItemGen["src/game/generation/itemGen.ts"]:::backend
            RoomGen["src/game/generation/roomGen.ts"]:::backend
            ActionGen["src/game/generation/actionGen.ts"]:::backend
            GenUtils["src/game/generation/utils.ts"]:::backend
        end
        OpenAI["src/lib/openai.ts"]:::external
        Gemini["src/lib/gemini.ts"]:::external
        DataStore["game-server/data/"]:::external
        Memory["Memory Store (future)"]:::external
    end

    %% External Services
    subgraph "External LLM Services"
        classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
        extOpenAI["OpenAI API"]:::external
        extGemini["Gemini API"]:::external
    end

    %% Frontend interactions
    FEEntrypoint -->|"renders UI"| UILayer
    UILayer -->|"uses primitives"| UIPrimitives
    FEEntrypoint -->|"calls REST"| APIClient
    FEEntrypoint -->|"opens WS"| SocketClient

    %% Client-Server communication
    SocketClient -->|"player_action"| BEEntrypoint
    BEEntrypoint -->|"serves assets"| APIClient
    BEEntrypoint --> Actions
    BEEntrypoint --> State

    %% Game flow
    Actions --> State
    Actions --> MapGen
    Actions --> MonsterGen
    Actions --> ItemGen
    Actions --> RoomGen
    Actions --> ActionGen

    MapGen --> GenUtils
    MonsterGen --> GenUtils
    ItemGen --> GenUtils
    RoomGen --> GenUtils
    ActionGen --> GenUtils

    Actions --> OpenAI
    Actions --> Gemini
    State --> DataStore
    BEEntrypoint --> Memory
    Memory --> State

    %% Responses
    State -->|"state_update"| SocketClient

    %% LLM Connectors to APIs
    OpenAI --> extOpenAI
    Gemini --> extGemini

    %% Click Events
    click FEEntrypoint "https://github.com/cktang88/dungeon-game/blob/super-easy/game-client/src/main.tsx"
    click UILayer "https://github.com/cktang88/dungeon-game/tree/super-easy/game-client/src/components/"
    click UIPrimitives "https://github.com/cktang88/dungeon-game/tree/super-easy/game-client/src/components/ui/"
    click APIClient "https://github.com/cktang88/dungeon-game/blob/super-easy/game-client/src/lib/api.ts"
    click SocketClient "https://github.com/cktang88/dungeon-game/blob/super-easy/game-client/src/lib/socket.ts"
    click BEEntrypoint "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/index.ts"
    click Actions "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/game/actions.ts"
    click State "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/game/state.ts"
    click MapGen "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/game/generation/mapGen.ts"
    click MonsterGen "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/game/generation/monsterGen.ts"
    click ItemGen "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/game/generation/itemGen.ts"
    click RoomGen "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/game/generation/roomGen.ts"
    click ActionGen "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/game/generation/actionGen.ts"
    click GenUtils "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/game/generation/utils.ts"
    click OpenAI "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/lib/openai.ts"
    click Gemini "https://github.com/cktang88/dungeon-game/blob/super-easy/game-server/src/lib/gemini.ts"
    click DataStore "https://github.com/cktang88/dungeon-game/tree/super-easy/game-server/data/"

    %% Styles
    class FEEntrypoint,UILayer,UIPrimitives,APIClient,SocketClient frontend
    class BEEntrypoint,Actions,State,MapGen,MonsterGen,ItemGen,RoomGen,ActionGen,GenUtils backend
    class OpenAI,Gemini,DataStore,Memory,extOpenAI,extGemini external
```
