# gstones/moke-kit architecture

> Architecture diagram of the GitHub repository gstones/moke-kit, 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/gstones/moke-kit
- Repository: https://github.com/gstones/moke-kit

## Overview

##### Main Components
- Application Layer – Represent the application entry point and the dependency injection system that ties together all components (see the fxmain directory and the usage of uber/fx).
- Server Layer – Comprises multiple server types:
- gRPC Server (server/internal/srpc)
- HTTP Gateway (server for grpc-gateway)
- TCP, WebSocket, and KCP servers (using the zinx framework within server/internal/zinx)
- Middleware Layer – Contains components such as:
- Authentication (server middlewares and related auth files in 3rd/auth)
- Rate Limiting, Logging, Recovery, and OpenTelemetry (implemented in server middlewares & sfx)
- Storage Layer – Includes:
- Database functionality (GORM in orm/pkg/ofx and MongoDB in orm/nosql/mongo)
- Cache support (Redis cache and Dragonfly support)
- Message Queue (mostly using NATS, with the mq directory containing various implementations and adapters)
- Integration Layer – Houses external integrations:
- IAP (in 3rd/iap for purchase receipt verification)
- Agones (in 3rd/agones for gaming server management on Kubernetes)

##### Relationships and Interactions
- Start at the Application Layer where the Application component initializes via dependency injection.
- DI then “wires” to various Server components, each of which is instrumented with Middleware such as authentication, rate-limiting, logging, etc.
- Each middleware component may access the Storage Layer (databases, caches) and be involved in message dispatch operations (using the Message Queue).
- Integration components (IAP, Agones) are accessible from the middleware or directly from the service logic for specialized tasks.
- The interactions imply that after a request enters through one of the server protocols, it gets processed via middleware and then uses various storage and integration modules based on its needs.

##### Important Architectural Patterns and Design Principles
- Modularity: The project is organized into clearly defined modules (3rd, auth, cloud, orm, server, mq, etc.) that encapsulate different concerns.
- Dependency Injection: Using uber/fx promotes decoupling and easier testing by allowing modules to be swapped simply.
- Middleware chaining: A clear separation between protocol-specific servers and shared middleware.
- Clean separation between message queue implementations, caching, and persistence layers.

##### Relevant Technologies and Libraries
- Go as the primary programming language.
- Uber/fx for dependency injection.
- gRPC, grpc-gateway for API communication.
- TCP/WebSocket/KCP handled partly by the zinx framework.
- GORM for relational databases and MongoDB driver for NoSQL.
- Redis and Dragonfly for caching.
- NATS for messaging.
- IAP libraries and Agones SDK for third party integrations.
- Various utility packages and logging frameworks (zap logger and custom logger components).

- Use clear labels for each component (e.g., Application, DI Container, gRPC Server, HTTP Gateway, TCP Server, Middleware components, GORM/MongoDB, Redis/Dragonfly, NATS MQ, IAP, Agones).
- The flow from the Application Layer (starting point) to the various Server components.
- Connection lines from the servers to the middleware that encloses shared functionality like authentication and rate limiting.
- Flow from middleware or service logic to storage systems and third-party integration modules.
- Integration components (yet another distinct style)
- Modular structure visible in the file tree by optionally drawing a “module container” that represents components such as “auth”, “cloud”, “iap”, “mq”, “orm”, and “server”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        app["App & DI (fxmain)"]:::app
    end

    %% Server Layer
    subgraph "Server Layer"
        grpc["gRPC Server"]:::server
        gateway["HTTP Gateway"]:::server
        zinx["TCP/WebSocket/KCP Server (zinx)"]:::server
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        auth["Auth Middleware"]:::mw
        stdmw["Other Middlewares (Logging,RateLimit,Recovery,OTel)"]:::mw
    end

    %% Storage & Message Queue Layer
    subgraph "Storage & Message Queue Layer"
        gorm["Relational DB (GORM)"]:::storage
        mongo["NoSQL DB (MongoDB)"]:::storage
        cache["Cache (Redis & Dragonfly)"]:::storage
        nats["Message Queue (NATS)"]:::storage
    end

    %% Integration Layer
    subgraph "Integration Layer"
        iap["IAP Integration"]:::integration
        agones["Agones Integration"]:::integration
    end

    %% Connections from Application Layer to Server Layer 
    app -->|"initializes"| grpc
    app -->|"initializes"| gateway
    app -->|"initializes"| zinx

    %% Connections from Server Layer to Middleware Layer
    grpc -->|"processed by"| auth
    grpc -->|"processed by"| stdmw
    gateway -->|"processed by"| auth
    gateway -->|"processed by"| stdmw
    zinx -->|"processed by"| auth
    zinx -->|"processed by"| stdmw

    %% Connections from Middleware Layer to Storage & Message Queue Layer
    auth -->|"accesses"| gorm
    auth -->|"accesses"| mongo
    auth -->|"accesses"| cache
    auth -->|"accesses"| nats
    stdmw -->|"accesses"| gorm
    stdmw -->|"accesses"| mongo
    stdmw -->|"accesses"| cache
    stdmw -->|"accesses"| nats

    %% Connections from Middleware Layer to Integration Layer
    auth -->|"integrates"| iap
    auth -->|"integrates"| agones
    stdmw -->|"integrates"| iap
    stdmw -->|"integrates"| agones

    %% Styles
    classDef app fill:#D0E6A5,stroke:#333,stroke-width:2px;
    classDef server fill:#86E3CE,stroke:#333,stroke-width:2px;
    classDef mw fill:#FFDD94,stroke:#333,stroke-width:2px;
    classDef storage fill:#F09494,stroke:#333,stroke-width:2px;
    classDef integration fill:#A29BFE,stroke:#333,stroke-width:2px;

    %% Click Events
    click app "https://github.com/gstones/moke-kit/blob/main/fxmain/fxmain.go"
    click grpc "https://github.com/gstones/moke-kit/blob/main/server/internal/srpc/grpc.go"
    click gateway "https://github.com/gstones/moke-kit/blob/main/server/internal/srpc/gateway.go"
    click zinx "https://github.com/gstones/moke-kit/blob/main/server/internal/zinx/zinx_tcp.go"
    click auth "https://github.com/gstones/moke-kit/blob/main/3rd/auth/pkg/authfx/firebase_middleware.go"
    click stdmw "https://github.com/gstones/moke-kit/blob/main/server/middlewares/logger.go"
    click gorm "https://github.com/gstones/moke-kit/blob/main/orm/pkg/ofx/gorm_module.go"
    click mongo "https://github.com/gstones/moke-kit/blob/main/orm/nosql/mongo/factory.go"
    click cache "https://github.com/gstones/moke-kit/blob/main/orm/nosql/cache/redis_cache.go"
    click nats "https://github.com/gstones/moke-kit/blob/main/mq/internal/nats/message_queue.go"
    click iap "https://github.com/gstones/moke-kit/blob/main/3rd/iap/pkg/iapfx/iap_clients.go"
    click agones "https://github.com/gstones/moke-kit/tree/main/3rd/agones/pkg/agonesfx"
```
