# jjoriping/kkutu architecture

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

- Interactive diagram: https://gitdiagram.com/jjoriping/kkutu
- Repository: https://github.com/jjoriping/kkutu

## Overview

##### Main Components Identification
The system consists of two primary server components and several supporting services:

a. Game Server (Server/lib/Game/)
- Handles game logic and real-time gameplay
- Manages different game modes (classic, crossword, typing, etc.)
- Controls robot players and shop functionality

b. Web Server (Server/lib/Web/)
- Manages user interface and authentication
- Handles static assets and client-side resources
- Provides REST APIs for game operations

c. Supporting Services
- PostgreSQL Database (for persistent storage)
- Redis (optional, for rankings and sessions)
- Multiple OAuth providers for authentication

**Client Layer**
- Web Browser
- Mobile Browser (indicated by m_* files)

**Frontend Layer (Server/lib/Web/public/)**
- CSS Styles
- JavaScript Components
- Media Assets
- Views (Pug templates)

**Application Layer**
- Web Server Cluster
- Authentication Module
- Route Handlers
- WebSocket Manager
- Game Server Cluster
- Game Modes
- Room Management
- Player Management

**Data Layer**
- PostgreSQL Database
- Redis Cache (optional)

**External Services Layer**
- OAuth Providers
- Google
- Facebook
- Twitter
- Others

##### Key Architectural Patterns to Highlight

a. Clustering Architecture
- How the game server uses clustering for scalability
- Master-slave relationship in game servers

b. Real-time Communication
- WebSocket connections between clients and game server
- Internal communication between web and game servers

c. Authentication Flow
- Multiple OAuth provider integration
- Session management

Use the following visual elements:

- Rectangles: Server components
- Clouds: External services
- Hexagons: Client applications

b. Connection Types:

- Blue: Core server components
- Green: Database systems
- Orange: External services
- Purple: Client-side components

##### Important Details

a. Port Configurations:
- Reserved IP (127.0.0.2) for internal communication
- Public-facing ports

b. Game Logic Flow:
- Room creation and management
- Player interactions
- Game state management

c. Data Flow:
- User authentication process
- Game state updates
- Score and ranking updates

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Browser["Web Browser"]
        MBrowser["Mobile Browser"]:::mobile
        click MBrowser "https://github.com/JJoriping/KKuTu/blob/master/Server/lib/Web/views/m_*.pug"
    end

    subgraph Frontend
        CSS["CSS Styles"]:::frontend
        JS["JavaScript Components"]:::frontend
        Media["Media Assets"]:::frontend
        Views["View Templates"]:::frontend
        GameClient["Game Client Logic"]:::frontend
        
        click CSS "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Web/public/css/"
        click JS "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Web/public/js/"
        click Media "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Web/public/media/"
        click Views "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Web/views/"
        click GameClient "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Web/lib/kkutu/"
    end

    subgraph "Application Layer"
        subgraph "Web Server Cluster"
            WebCore["Web Server Core"]
            AuthModule["Authentication Module"]
            RouteHandler["Route Handlers"]
            WSManager["WebSocket Manager"]
            DBManager["Database Manager"]
            LangSupport["Language Support"]
            
            click WebCore "https://github.com/JJoriping/KKuTu/blob/master/Server/lib/Web/main.js"
            click AuthModule "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Web/auth/"
            click RouteHandler "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Web/routes/"
            click DBManager "https://github.com/JJoriping/KKuTu/blob/master/Server/lib/Web/db.js"
            click LangSupport "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Web/lang/"
        end

        subgraph "Game Server Cluster"
            GameCore["Game Server Core"]
            Master["Master Server"]
            Slave["Slave Server"]
            GameModes["Game Modes"]
            RoomMgmt["Room Management"]
            PlayerMgmt["Player Management"]
            Robot["Robot System"]
            Shop["Shop System"]
            
            click GameCore "https://github.com/JJoriping/KKuTu/blob/master/Server/lib/Game/kkutu.js"
            click Master "https://github.com/JJoriping/KKuTu/blob/master/Server/lib/Game/master.js"
            click Slave "https://github.com/JJoriping/KKuTu/blob/master/Server/lib/Game/slave.js"
            click GameModes "https://github.com/JJoriping/KKuTu/tree/master/Server/lib/Game/games/"
            click Robot "https://github.com/JJoriping/KKuTu/blob/master/Server/lib/Game/robot.js"
            click Shop "https://github.com/JJoriping/KKuTu/blob/master/Server/lib/Game/shop.js"
        end
    end

    subgraph "Data Layer"
        PostgreSQL[(PostgreSQL)]:::database
        Redis[(Redis Cache)]:::database
    end

    subgraph "External Services"
        OAuth{{"OAuth Providers"}}:::external
        Google{{"Google"}}:::external
        Facebook{{"Facebook"}}:::external
        Twitter{{"Twitter"}}:::external
    end

    %% Connections
    Browser --> CSS & JS & Media & Views
    MBrowser --> CSS & JS & Media & Views
    
    CSS & JS & Media & Views --> WebCore
    GameClient --> WSManager
    
    WebCore --> AuthModule
    WebCore --> RouteHandler
    WebCore --> WSManager
    WebCore --> DBManager
    WebCore --> LangSupport
    
    AuthModule --> OAuth
    OAuth --> Google & Facebook & Twitter
    
    WSManager -.-> GameCore
    GameCore --> Master
    Master --> Slave
    Master --> GameModes & RoomMgmt & PlayerMgmt
    Slave --> Robot & Shop
    
    DBManager --> PostgreSQL
    DBManager -.-> Redis
    
    %% Styles
    classDef frontend fill:#d8b4fe,stroke:#000
    classDef database fill:#86efac,stroke:#000
    classDef external fill:#fdba74,stroke:#000
    classDef mobile fill:#93c5fd,stroke:#000

    %% Legend
    subgraph Legend
        L1["Frontend Component"]:::frontend
        L2[(Database)]:::database
        L3{{"External Service"}}:::external
        L4["Mobile Interface"]:::mobile
    end
```
