Architecture

System Architecture

This document describes the technical architecture, component relationships, data flow, and security mechanisms of CROSS.

---

🏗️ High-Level Component Diagram

graph TD
    subgraph Twitch Infrastructure
        TC[Twitch Chat]
        TE[Twitch Overlay Extension / HTML5]
    end

    subgraph Streamer Setup
        OBS[OBS Studio / Streamlabs]
        GC[Godot Desktop App / Executable]
    end

    subgraph CROSS Core Backend
        MS[Master Server: C# / ASP.NET Core]
        KC[Keycloak Auth Service]
        DB[(Central Database: PostgreSQL)]
    end

    TC -- IRC/WebSockets --> MS
    TE -- WebSockets / HTTPS --> MS
    GC -- WebSockets --> MS
    MS -- OIDC / OAuth2 --> KC
    MS -- SQL --> DB
    OBS -- Game Capture with Transparency --> GC

---

🖥️ Component Breakdown

1. Central Master Server

The backbone of the system.

• Responsibilities:
  • Maintain the global game state (which characters are active on which stream).
  • Handle combat calculation, enemy spawning algorithms, and experience/resource awards.
  • Provide WebSockets for real-time, low-latency game events.
  • Expose REST APIs for Twitch Webhooks, authentication, and inventory management.
• Technology Stack (Candidate):
  • C# with ASP.NET Core Web API and SignalR (WebSockets) for real-time multiplayer session state updates and API endpoints. Allows direct class reuse in Godot C# client.

2. Client Rendering & Control Progression

We implement client rendering and viewer controls in a multi-step roadmap to scale features cleanly:

• Step 1: Twitch Chat Commands (MVP Overlay)
  • Implementation: A Godot 4 WebGL client exported as a Web Browser Source or Desktop Client running on the streamer’s OBS.
  • Flow: Reads Twitch Chat commands via the Master Server. Viewers change their character states (e.g. !attack, !defend) which triggers server-authoritative state transitions rendered on stream.
• Step 2: Standalone Client Spectator & Interaction Sync
  • Implementation: Viewers launch the Standalone Godot Solo Client on their PCs.
  • Flow: Viewers can input a streamer’s channel name inside their standalone game client to spectate the streamer’s base. The local client connects to the Master Server’s stream session, rendering the action locally and allowing viewers to cast active spells, click-target enemies, and manage inventories in real-time with zero-latency visual feedback.
• Step 3: Twitch Overlay Extension (Post-MVP)
  • Implementation: Lightweight HTML5 panel loaded on top of the Twitch video player.
  • Flow: Interacts directly with the Master Server to trigger attacks, select abilities, and display inventory without requiring chat commands or a separate standalone download.

3. Dynamic Asset Pipeline & Spritesheet Compiler

To support custom streamer-uploaded assets (for custom rooms, enemies, or cosmetics) without killing bandwidth:

• Automatic Packaging: When a streamer uploads custom artwork through the developer dashboard, the Master Server dynamically compiles the images into a unified Streamer Spritesheet (along with a JSON atlas map).
• Caching & Delivery: The Godot overlay client and standalone spectator clients download this single spritesheet for the streamer’s session, minimizing HTTP handshake overhead and optimizing GPU memory loading.

---

4. Authentication (Keycloak & Twitch OAuth)

• Identity Provider: Keycloak handles registration, login, session tokens, and security.
• Integration: Streamers log into the CROSS dashboard web app using Keycloak configured with Twitch as an OAuth provider.
• Viewer Auth:
  • Chat commands: Authenticated by Twitch IRC user tags (username & user ID).
  • Extension: Authenticated using the signed Twitch JWT token, matched against their Keycloak user profile if they link accounts for detailed progression.

---

🔒 Security & Anti-Cheat

Because the game features cross-channel progression, prevention of cheating and exploit farming is critical.

1. Server-Authoritative Game Loop:
   • All state computations (combat, damage, movements, resource collection) are performed on the Master Server.
   • The Godot clients are purely rendering targets (dumb clients). They receive state updates and render them. They cannot dictate damage values or gold gains.
2. Rate Limiting & Command Verification:
   • WebSocket messages are authenticated and rate-limited.
   • Command validation: The server verifies player cooldowns and distance ranges before applying actions like !strike or !heal.
3. Exploit/AFK Checks:
   • The server flags channels that have suspiciously high resource generation rates (e.g., private streams running loop bots) and suspends/limits rewards in those channels.