Platform Architecture

Guide for Platform Architecture

Platform Architecture: "The Boilerplate & The Game"

This document outlines the architectural strategy for Legends of Hastinapur and future titles. The goal is to separate the "Universal Infrastructure" (Identity, Billing, Social) from the "Gameplay Logic" (Simulacrum, Unity, Unreal).

Core Philosophy: "Game Infrastructure as a Service"

We treat the account-api and associated workers as a centralized Platform that provides essential services to multiple Game Nodes (Tenants).

The 3-Layer Model

  1. Layer 1: The Platform (Cloudflare Workers)
    • Responsibility: Identity (Auth), Billing (Shop/Cashfree), Social (Friends/Guilds), and Persistent Data (Items/Inventory).
    • State: Global, Persistent, Multi-tenant.
    • Key Services: account-api, shop-api.
  2. Layer 2: The Hotwire (Webhooks/Events)
    • Responsibility: The integration glue. The Platform fires events to Game Nodes; Game Nodes call Platform APIs.
    • Pattern: "Fire and Forget" for events.
    • Examples:
      • user.created -> Game initializes player stats.
      • payment.success -> Game grants item access.
  3. Layer 3: The Game Node (AWS / Docker)
    • Responsibility: Pure gameplay logic, physics, simulation.
    • State: Session-based, Real-time.
    • Examples: rust-engine (Simulacrum), Unity Headless Server.
    • Trust: Trusts the Platform's JWT signature.

Integration Guide: Onboarding a New Game

To "hotwire" a new game into this infrastructure:
  1. Register Tenant: Create a new entry in tenants table in account-api.
  2. Configure Webhooks: Provide a webhook_url where the Platform will send events (e.g., https://api.new-game.com/webhooks).
  3. Implement Auth:
    • Client logs in via Platform (account-api/auth/login).
    • Client receives JWT.
    • Client connects to Game Server with JWT.
    • Game Server verifies JWT signature using Platform Public Key.

Authentication & Security

  • Multi-tenancy: Strictly enforced via client_id and DB schemas.
  • Tenant Policies: Tenants can toggle "Force 2FA" on/off.
  • User Tiers (Legends of Hastinapur Policy):
    • Member: Email/Pass + Forced TOTP + Email Recovery.
    • Free: Email/Pass + Forced TOTP (No Recovery).