# ill-inc/biomes-game architecture

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

- Interactive diagram: https://gitdiagram.com/ill-inc/biomes-game
- Repository: https://github.com/ill-inc/biomes-game

## Overview

##### Project type and purpose
- Biomes is a full-stack, web-based sandbox MMORPG. It combines a Next.js/React frontend, WebAssembly game engine modules (C++/Rust → WASM via Bazel), and a polyglot, distributed backend written in TypeScript/Node.js (dozens of microservices) plus shared C++ libraries (“voxeloo”).
- It’s deployed on Kubernetes (see deploy/k8/) and uses Redis, Firestore, SQL and Cloud Storage for persistence.

##### File structure
- Top‐level “src/client” and “src/pages” → Next.js React frontend (SPA + SSR + API routes).
- “src/server/web” → standalone Node.js/Express app backing web UI and admin REST endpoints.
- “src/server/…” (anima, chat, gaia_v2, logic, map, sync, spawn, etc.) → ~16 specialized backend services, each compiled from TS, tied together via zrpc/gRPC, Redis pub/sub and service discovery (“server/shared/discovery”).
- “server/shared” → cross‐cutting libraries (auth, config, cache, storage, zrpc, pubsub, tasks).
- “src/shared” → client + server shared TypeScript libraries (data models, ECS, game logic, C++→WASM bindings).
- “voxeloo” → core C++ modules for terrain, biomes, galois, WebAssembly extensions.
- “deploy/k8” → Kubernetes manifests for each component.

##### README
- Confirms Next.js/TypeScript/WebAssembly/React stack.
- Mentions distributed architecture that can also run locally.
- Documentation points to running dozens of services locally via Bazel and devcontainer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers from top to bottom
    %% Browser / Client Layer
    subgraph "Browser / Client" 
        direction TB
        Browser["Browser<br/>(React + WASM)"]:::frontend
        click Browser "https://github.com/ill-inc/biomes-game/tree/main/src/client"
        WASMLoader["WASM Loader & Bindings"]:::frontend
        click WASMLoader "https://github.com/ill-inc/biomes-game/tree/main/src/shared/wasm"
        Browser -->|"loads WASM modules"| WASMLoader
    end

    %% API Gateway / SSR Layer
    subgraph "API Gateway / SSR" 
        direction TB
        NextJS["Next.js Server<br/>(SSR & API)"]:::api
        click NextJS "https://github.com/ill-inc/biomes-game/tree/main/src/pages"
        APIroutes["API Routes"]:::api
        click APIroutes "https://github.com/ill-inc/biomes-game/tree/main/src/pages/api"
        NextJS -->|"serves pages & REST"| Browser
        NextJS -->|"calls API routes"| APIroutes
    end

    %% Real-time Layer
    subgraph "Real-time Entrypoint" 
        direction TB
        ZRPC["WebSocket / zrpc Endpoint"]:::api
        Balancer["Load Balancer"]:::api
        click Balancer "https://github.com/ill-inc/biomes-game/tree/main/src/server/balancer"
        ZRPC -->|"routes ws requests"| Balancer
        Balancer -->|"dispatch to microservices"| Microservices
    end

    %% Microservices Layer
    subgraph "Game Microservices" 
        direction TB
        classDef svc fill:#ffa500,stroke:#333,stroke-width:1px
        Microservices["Microservices Cluster"]:::svc
        click Microservices "https://github.com/ill-inc/biomes-game/tree/main/src/server"
        subgraph "Examples"
            anima["anima"]:::svc
            click anima "https://github.com/ill-inc/biomes-game/tree/main/src/server/anima"
            chat["chat"]:::svc
            click chat "https://github.com/ill-inc/biomes-game/tree/main/src/server/chat"
            gaia["gaia_v2"]:::svc
            click gaia "https://github.com/ill-inc/biomes-game/tree/main/src/server/gaia_v2"
            logic["logic"]:::svc
            click logic "https://github.com/ill-inc/biomes-game/tree/main/src/server/logic"
            map["map"]:::svc
            click map "https://github.com/ill-inc/biomes-game/tree/main/src/server/map"
            sync["sync"]:::svc
            click sync "https://github.com/ill-inc/biomes-game/tree/main/src/server/sync"
            spawn["spawn"]:::svc
            click spawn "https://github.com/ill-inc/biomes-game/tree/main/src/server/spawn"
            bob["bob"]:::svc
            click bob "https://github.com/ill-inc/biomes-game/tree/main/src/server/bob"
        end
        Microservices --> anima
        Microservices --> chat
        Microservices --> gaia
        Microservices --> logic
        Microservices --> map
        Microservices --> sync
        Microservices --> spawn
        Microservices --> bob

        %% Shared Infrastructure usage
        subgraph "Shared Infrastructure Libs" 
            direction TB
            discovery["service discovery"]:::infra
            click discovery "https://github.com/ill-inc/biomes-game/tree/main/src/server/shared/discovery"
            zrpc_lib["zrpc"]:::infra
            click zrpc_lib "https://github.com/ill-inc/biomes-game/tree/main/src/server/shared/zrpc"
            pubsub["pub/sub"]:::infra
            click pubsub "https://github.com/ill-inc/biomes-game/tree/main/src/server/shared/pubsub"
            storage_lib["storage"]:::infra
            click storage_lib "https://github.com/ill-inc/biomes-game/tree/main/src/server/shared/storage"
        end
        Microservices --> discovery
        Microservices --> zrpc_lib
        Microservices --> pubsub
        Microservices --> storage_lib
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        Redis["Redis<br/>(Cache + Pub/Sub)"]:::datastore
        Firestore["Firestore<br/>(World Persistence)"]:::datastore
        SQLDB["Postgres/SQL"]:::datastore
        GCS["Cloud Storage"]:::datastore
        Balancer --> Redis
        anima --> Redis
        chat --> Redis
        gaia --> Firestore
        logic --> SQLDB
        map --> Firestore
        sync --> Redis
        spawn --> Firestore
        bob --> SQLDB
    end

    %% External Auth
    subgraph "External Auth Providers" 
        direction TB
        OAuth["OAuth (Discord/Google/Twitch)"]:::external
        NextJS -->|"OAuth redirects"| OAuth
    end

    %% Deployment / Orchestration
    subgraph "Deployment / Orchestration" 
        direction TB
        K8s["Kubernetes Cluster"]:::infra
        click K8s "https://github.com/ill-inc/biomes-game/tree/main/deploy/k8"
        K8s --> Microservices
        K8s --> NextJS
        K8s --> Balancer
    end

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef api fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef svc fill:#ffe5b4,stroke:#984f01,stroke-width:1px
    classDef infra fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef datastore fill:#f8f9fa,stroke:#343a40,stroke-width:1px
    classDef external fill:#f5c6cb,stroke:#721c24,stroke-width:1px
```
