# phuhao00/nakama architecture

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

- Interactive diagram: https://gitdiagram.com/phuhao00/nakama
- Repository: https://github.com/phuhao00/nakama

## Overview

##### Main Components
- Client Interfaces: Outline various client types (mobile apps, web clients, game engines) that interact via different protocols such as REST (HTTP/JSON), gRPC, WebSockets, and rUDP.
- API Gateways & Protocol Layers: Represent protocol-specific endpoints. There are separate “apigrpc” and “console” directories that indicate gRPC interfaces and an embedded web console (with an Angular UI) respectively.
- Core Server Modules: The “server” directory contains many API endpoints (e.g., account, authentication, channels, matchmaking, notifications, social, tournaments, etc.). Group these together under a “Core Server / Business Logic” layer. This layer also encompasses specialized components for session management, matchmaking, leaderboards, runtime code execution (supporting Lua, JavaScript, and Go) and more.
- Runtime Extension/Subsystems: Highlight the runtime modules (evident in subdirectories like “internal/gopher-lua”, “internal/cronexpr”, and pluginbuilder components). These allow for extending server functionality via custom scripts.
- Build & Deployment Infrastructure: Optionally note the “build” directory with Dockerfiles and deployment scripts, and include CI/CD pipelines (e.g., GitHub workflows for tests and Docker builds) to show how the system is packaged and deployed.

##### Establish Relationships and Interactions
- From the API layer, connect to the Core Server modules where authentication, social, matchmaking, chat, and other game logic functions are executed.
- Link the Core Server to the Database, indicating bidirectional communication (queries/updates).
- For the Console UI, show it as an embedded component in the binary that communicates with the same backend APIs.

##### Important Architectural Patterns and Design Principles
- Modularity: Emphasize how the codebase is partitioned (e.g., separate packages for different functional areas like authentication, channels, matchmaking).
- Protocol Abstraction: Show that multiple protocols (gRPC, REST, WebSocket) funnel into unified core logic.
- Extensibility: Illustrate the plugin and runtime scripting capabilities, showing how the system can be extended without changing the core server.
- Single Binary with Multiple Roles: Note that the server binary includes both game server functions and the embedded admin console, yet they are logically separated.

##### Relevant Technologies and Frameworks
- Language/Runtime: Go (with built-in modules and vendor dependencies).
- Protocol Buffers and gRPC: For service definitions and efficient communication.
- Angular: UI framework for the admin console.
- Docker & CI/CD tools: Used for build automation and containerization (as evident in the “build” and “.github/workflows” directories).
- Database: CockroachDB/Postgres for persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Mobile["Mobile Clients"]:::client
        Web["Web Clients"]:::client
        Game["Game Engine Clients"]:::client
    end

    subgraph "API Gateways & Protocol Layers"
        REST["REST (HTTP/JSON)"]:::api
        GRPC["gRPC Interface"]:::api
        WS["WebSockets"]:::api
        rUDP["rUDP"]:::api
        Console["Console UI"]:::console
    end

    Mobile -->|"HTTP"| REST
    Web -->|"HTTP"| REST
    Game -->|"gRPC"| GRPC
    Game -->|"rUDP"| rUDP
    Mobile -->|"WS"| WS
    Web -->|"WS"| WS

    REST -->|"API_Calls"| Core["Core Server / Business Logic"]:::server
    GRPC -->|"API_Calls"| Core
    WS -->|"API_Calls"| Core
    rUDP -->|"API_Calls"| Core
    Console -->|"Admin_Commands"| Core

    Core -->|"Executes_Script"| Lua["Lua Runtime"]:::runtime
    Core -->|"Parses_Cron"| Cron["Cron Expression Parser"]:::runtime
    Core -->|"Builds_Plugin"| Plugin["Plugin Builder"]:::runtime

    Core -->|"Reads_Writes"| DB["Database (CockroachDB/Postgres)"]:::db

    subgraph "Build & Deployment"
        Build["Build Scripts & Dockerfiles"]:::build
        CICD["CI/CD Pipelines"]:::build
    end

    Build -->|"Deploys"| Core
    CICD -->|"Triggers"| Core

    click GRPC "https://github.com/phuhao00/nakama/tree/master/apigrpc/"
    click Console "https://github.com/phuhao00/nakama/tree/master/console/"
    click Core "https://github.com/phuhao00/nakama/tree/master/server/"
    click Lua "https://github.com/phuhao00/nakama/tree/master/internal/gopher-lua/"
    click Cron "https://github.com/phuhao00/nakama/tree/master/internal/cronexpr/"
    click Plugin "https://github.com/phuhao00/nakama/tree/master/build/pluginbuilder/"
    click Build "https://github.com/phuhao00/nakama/tree/master/build/"
    click CICD "https://github.com/phuhao00/nakama/tree/master/.github/workflows/"

    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef api fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef server fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef runtime fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef db fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef build fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef console fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
