system architecture

Guide for system architecture

System Architecture - Legends of Hondø (Hybrid Cloud)

This document serves as the Single Source of Truth for the end-to-end technical architecture of Legends of Hondø (LOH). It defines the Hybrid Cloud Architecture combining Cloudflare Edge Services with a centralized Rust Backend.

High-Level Architecture

graph TD
    User["User (Player)"]
    Admin["Admin (Ops)"]
    
    subgraph Edge ["Edge Layer (Cloudflare)"]
        DNS["DNS & WAF"]
        Pages_Web["Pages: loh-website"]
        Pages_Ops["Pages: loh-ops-tools"]
        Workers["Workers: loh-cf-workers"]
        
        subgraph EdgeData ["Edge Data"]
            D1[("D1: KB & Tickets")]
            R2[("R2: Assets & Docs")]
        end
    end
    
    subgraph Backend ["Core Backend (GCP/Container)"]
        LB["Load Balancer"]
        GameServer["Game Server (Rust/Axum)"]
        AuthAPI["Auth/Payment API (Rust/Axum)"]
    end
    
    subgraph Data ["Core Data"]
        CRDB[("CockroachDB (Player Data)")]
        Redis[("Redis (Cache/PubSub)")]
    end

    User --> DNS
    Admin --> DNS
    
    DNS --> Pages_Web
    DNS --> Pages_Ops
    DNS --> Workers
    
    Workers --> D1
    Workers --> R2
    
    Pages_Web --> Workers
    Pages_Web --> LB
    
    Pages_Ops --> Workers
    Pages_Ops --> LB
    
    LB --> GameServer
    LB --> AuthAPI
    
    GameServer --> CRDB
    GameServer --> Redis
    AuthAPI --> CRDB

1. Client Layer

Game Client (loh-game) and Website (loh-website)

  • Game: Rust/Bevy (Native/WASM). Connects via WebSocket to Core Backend.
  • Website: Next.js (Cloudflare Pages). Connects to Workers (Content) and Core Backend (Auth).

Ops Tools (loh-ops-tools)

  • Platform: Next.js (Cloudflare Pages).
  • Role: Internal dashboards for Game Masters and Developers.
  • Connectivity:
    • Reads Docs/Tickets directly from Cloudflare D1.
    • Reads Player Data by proxing through Core Backend APIs (to avoid direct DB connections from Edge).

2. Edge Layer (loh-cf-workers)

We use Cloudflare for global, low-latency logic that doesn't require high-frequency game state synchronization.
  • kb-api: Serves Knowledge Base and Support Ticket logic.
    • Data Source: Cloudflare D1 (Structured) + R2 (Markdown/Assets).
  • Routing: Handles custom domains (kb-api.legendsofhastinapur.com).

3. Core Backend (loh-backend)

The authoritative server for Gameplay, Economy, and Authentication. Hosted on containerized infrastructure (e.g., GCP) to allow persistent TCP connections and high-performance compute.
  • Runtime: Tokio (Async Rust).
  • Framework: Axum (Web/WebSocket).
  • Services:
    • Game Server: Real-time WebSocket game logic.
    • Auth/Ecom: REST APIs for login and payments.
  • Database Access: Exclusive direct access to CockroachDB.

4. Data Layer

Core Data: CockroachDB (loh-data)

  • Usage: Player Inventory, Stats, Transactions, Auth.
  • Why: Strong consistency, horizontal scalability, Postgres compatibility.

Edge Data: Cloudflare D1

  • Usage: Knowledge Base content index, Support Tickets, FAQs.
  • Why: Instant access from Edge Workers, lower cost for read-heavy text data.

Asset Storage: Cloudflare R2

  • Usage: Game assets, Markdown docs, Images.
  • Why: Zero egress fees.

Cache: Redis

  • Usage: Session management, Real-time Pub/Sub, Leaderboards.

5. Shared Logic (loh-libs)

  • shared-protocol: Defines the wire format (MessagePack/JSON) used by Client, Edge, and Backend.
  • shared-logic: Deterministic game rules shared by Client prediction and Server authority.