# moke-game/platform architecture

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

- Interactive diagram: https://gitdiagram.com/moke-game/platform
- Repository: https://github.com/moke-game/platform

## Overview

Based on our analysis of the file tree and the README, this project is a full-featured service platform—a mid-tier system that exposes a collection of microservices providing features such as authentication, analytics (BI logging), buddy management, chat (private/group/room chats), knapsack (inventory), leaderboard, mail, matchmaking, party management, player profile, and room management (with lockstep frame synchronization). The services are implemented as independent microservices (each with its own “service” and often a corresponding “client” entrypoint) and are defined via Protocol Buffers in the “api” directory. In addition, the project clearly separates “private” and “public” versions of each service (where private services are not JWT validated and are only accessible via mTLS, and public services require JWT authentication along with mTLS). There is robust containerization (using Docker and Kubernetes in the “deployment” folder) and automated CI/CD workflows provided in “.github/workflows.”

##### Main Components
- Client/Consumer Layer: This includes interactive clients (as demonstrated by the “cmd/{service}/client” directories) and integration test clients.
- API Gateway / Edge Services (if applicable): Although not explicitly detailed, you might want to note that clients may interact with both public and private variants of the services, possibly via an API gateway or load balancer pattern.
- Service Communication: Include the internal communication channels among services using gRPC (as indicated by the generated proto GRPC files) and HTTP (the API gateways often expose REST endpoints, as indicated by the *_gw.go files).
- Data Storage / Database Layer: Represent databases or storage systems that each microservice uses (for example, “internal/db” directories exist in many services). Though specifics aren’t provided, assume there are underlying databases (SQL or NoSQL) and Redis caches (noted in key files and "redis" directories) used by several services.
- External Integrations: Note connections to external services – such as the matchmaking integration with Open Match and Agones, and external BI platforms like ThinkingData, MixPanel, and ClickHouse for the analytics service.

##### Relationships and Interactions
- Inter-service communication flows (for example, the Auth service might serve as a gatekeeper for other services by validating and issuing JWT tokens).

##### Architectural Patterns and Design Principles to Highlight
- Microservices Architecture: Emphasize that each service is independently developed/deployed.
- Dual Service Endpoints Pattern: Clearly separate “public” endpoints (which enforce JWT authentication) from “private” endpoints (used for internal communication secured using mTLS).
- Containerization and CI/CD: Note the use of Docker, Kubernetes, and a CI/CD pipeline (GitHub workflows) to ensure modern delivery practices.

##### Technologies, Frameworks, and Libraries
- Language: Golang (as seen by go.mod and go.sum).
- Communication: gRPC and HTTP (via REST gateways generated from proto definitions).
- Security: JWT tokens for authentication and mTLS for service-to-service communication.
- External Tools: Open Match and Agones for matchmaking, and analytics integrations with ThinkingData, MixPanel, local file, and ClickHouse.
- Container Deployment: Docker (with Dockerfile in build/package/docker) and Kubernetes (with configs in deployment/k8s).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client/Consumer Layer
    subgraph "Client/Consumer Layer"
        CA1["Auth Client"]:::client
        CA2["Chat Client"]:::client
        CA3["Other Clients"]:::client
        CT1["Auth Integration Tests"]:::test
    end

    %% API Gateway / Edge Services
    subgraph "API Gateway / Edge Services"
        GW1["Auth REST Gateway"]:::gateway
        GW2["Chat REST Gateway"]:::gateway
    end

    %% Microservices Layer
    subgraph "Microservices Layer"
        MI1["Auth Service (public/private)"]:::service
        MI2["Analytics Service (public/private)"]:::service
        MI3["Buddy Service (public/private)"]:::service
        MI4["Chat Service (public/private)"]:::service
        MI5["Knapsack Service (public/private)"]:::service
        MI6["Leaderboard Service (public/private)"]:::service
        MI7["Mail Service (public/private)"]:::service
        MI8["Matchmaking Service (public/private)"]:::service
        MI9["Party Service (public/private)"]:::service
        MI10["Profile Service (public/private)"]:::service
        MI11["Room Service (public/private)"]:::service
    end

    %% Data Storage / Database Layer
    subgraph "Data Storage / Database Layer"
        DB1["Auth DB/Redis"]:::database
        DB2["Buddy DB"]:::database
        DB3["Knapsack DB"]:::database
        DB4["Leaderboard DB"]:::database
        DB5["Profile Redis"]:::database
    end

    %% External Integrations
    subgraph "External Integrations"
        EX1["Analytics BI (ThinkingData,MixPanel,ClickHouse)"]:::external
        EX2["Matchmaking (Agones/OpenMatch)"]:::external
    end

    %% API Definitions / Contracts
    subgraph "API Definitions / Contracts"
        API["API Contracts (Protobuf)"]:::apicontracts
    end

    %% Containerization & Deployment
    subgraph "Containerization & Deployment"
        DOCKER["Docker"]:::container
        KUBE["Kubernetes"]:::container
        CI["CI/CD (GitHub Workflows)"]:::container
    end

    %% Connections between Layers
    %% Client Layer to API Gateway
    CA1 -->|"requests"| GW1
    CA2 -->|"requests"| GW2
    CA3 -->|"requests"| GW1
    CT1 -->|"tests"| GW1

    %% API Gateway to Microservices (public endpoints)
    GW1 -->|"forwards"| MI1
    GW2 -->|"forwards"| MI4

    %% Inter-service communication (example flows)
    MI1 -->|"gRPC"| MI2
    MI4 -->|"gRPC"| MI1

    %% Microservices to Data Storage
    MI1 -->|"stores"| DB1
    MI3 -->|"stores"| DB2
    MI5 -->|"stores"| DB3
    MI6 -->|"stores"| DB4
    MI10 -->|"stores"| DB5

    %% Microservices to External Integrations
    MI2 -->|"BI calls"| EX1
    MI8 -->|"matchmaking"| EX2

    %% API Contracts used by Microservices
    API -->|"defines"| MI1
    API -->|"defines"| MI2
    API -->|"defines"| MI3
    API -->|"defines"| MI4
    API -->|"defines"| MI5
    API -->|"defines"| MI6
    API -->|"defines"| MI7
    API -->|"defines"| MI8
    API -->|"defines"| MI9
    API -->|"defines"| MI10
    API -->|"defines"| MI11

    %% Containerization & Deployment flow
    CI -->|"triggers build"| DOCKER
    DOCKER -->|"deploys to"| KUBE
    KUBE -->|"runs"| MI1

    %% Styles
    classDef client fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef gateway fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef database fill:#F4A460,stroke:#333,stroke-width:2px;
    classDef external fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef container fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef apicontracts fill:#F5DEB3,stroke:#333,stroke-width:2px;
    classDef test fill:#FFB6C1,stroke:#333,stroke-width:2px;

    %% Click Events
    click CA1 "https://github.com/moke-game/platform/tree/main/cmd/auth/client"
    click CA2 "https://github.com/moke-game/platform/tree/main/cmd/chat/client"
    click CT1 "https://github.com/moke-game/platform/tree/main/tests/auth"
    click GW1 "https://github.com/moke-game/platform/blob/main/api/gen/auth/api/auth.pb.gw.go"
    click GW2 "https://github.com/moke-game/platform/blob/main/api/gen/chat/api/chat.pb.gw.go"
    click MI1 "https://github.com/moke-game/platform/tree/main/services/auth"
    click MI2 "https://github.com/moke-game/platform/tree/main/services/analytics"
    click MI3 "https://github.com/moke-game/platform/tree/main/services/buddy"
    click MI4 "https://github.com/moke-game/platform/tree/main/services/chat"
    click MI5 "https://github.com/moke-game/platform/tree/main/services/knapsack"
    click MI6 "https://github.com/moke-game/platform/tree/main/services/leaderboard"
    click MI7 "https://github.com/moke-game/platform/tree/main/services/mail"
    click MI8 "https://github.com/moke-game/platform/tree/main/services/matchmaking"
    click MI9 "https://github.com/moke-game/platform/tree/main/services/party"
    click MI10 "https://github.com/moke-game/platform/tree/main/services/profile"
    click MI11 "https://github.com/moke-game/platform/tree/main/services/room"
    click DB1 "https://github.com/moke-game/platform/tree/main/services/auth/internal/db"
    click DB2 "https://github.com/moke-game/platform/tree/main/services/buddy/internal/db"
    click DB3 "https://github.com/moke-game/platform/tree/main/services/knapsack/internal/db"
    click DB4 "https://github.com/moke-game/platform/tree/main/services/leaderboard/internal/db"
    click DB5 "https://github.com/moke-game/platform/tree/main/services/profile/internal/db/redis"
    click EX1 "https://github.com/moke-game/platform/tree/main/services/analytics/internal/service/bi"
    click EX2 "https://github.com/moke-game/platform/tree/main/services/matchmaking/internal/agones"
    click DOCKER "https://github.com/moke-game/platform/tree/main/build/package/docker/Dockerfile"
    click KUBE "https://github.com/moke-game/platform/tree/main/deployment/k8s"
    click CI "https://github.com/moke-game/platform/tree/main/.github/workflows"
    click API "https://github.com/moke-game/platform/tree/main/api"
```
