🌐 Mission Control — Distributed Game Library & Multi-Service Cluster

Mission Control extends its capabilities with a distributed, load-balanced game-library architecture that decouples heavy web scraping, game launcher crawling, and AI classification from real-time client node synchronization and user library queries.

Multiple computers (Library Nodes) contribute their locally installed games and hard drive storage capacities into one unified catalog, centralized in Supabase and served to all clients.

---

🎯 Architecture & Load Balancing Overview

View Source Definition
SYSTEM ARCHITECTURE DIAGRAMMERMAID SVG ENGINE
Generating visual flowchart...

---

📊 Database Schema & Table Lifecycle

Understanding why tables start empty and how they populate:

---

🛠️ Microservices Cluster Components

1. Multi-Pool Load Balancer & API Gateway (load_balancer.py)

• Port: 8800 (Public cluster gateway)
• Features:
  • Routing Rules:
    • /api/nodes/*, /api/nodes/{id}/sync, /api/library/stats, /api/games/{id}/installations $\rightarrow$ Dispatched to Node Service Pool.
    • /api/games?installed_only=true $\rightarrow$ Dispatched to Node Service Pool.
    • /api/games/discover, /api/games/seed, /api/games/classify, /api/search, global /api/games $\rightarrow$ Dispatched to Catalog Discovery Pool.
  • Health Probes: Probes /health on all upstream nodes every 5 seconds. If an instance drops, traffic routes around it instantly.
  • Status HUD: Access http://localhost:8800/cluster/status for real-time load distribution, latency, and pool health.

2. Catalog & Web Discovery Service Pool (catalog_service.py)

• Default Ports: 8811, 8812
• Features:
  • Scrapes Steam, Epic, GOG, and RAWG APIs in parallel without blocking local users.
  • Runs background workers for multi-tier LLM classification (Gemini Flash, Llama 3.3 70B).
  • Automatically backfills Steam release dates, high-res covers, and developers.

3. User Library & Node Sync Service Pool (node_service.py)

• Default Ports: 8821, 8822
• Features:
  • Low-latency node registration, authentication token verification, and 15s heartbeats.
  • Ingests local game installations and links them to the master canonical_games dataset.
  • Runs the Offline Watchdog: marks nodes offline and games unavailable if heartbeats lapse $>45\text{s}$.

---

🚀 How to Run the Cluster

Option A: Local Development Cluster (One Command)

Launch the entire multi-instance cluster with unified colored log streaming:

Bash / Terminal
Copy
cd Gaming/distributed_server
python run_cluster.py --catalog-instances 2 --node-instances 2

Option B: Production Containerized (Docker Compose)

1. Build and Boot Cluster

Bash / Terminal
Copy
cd Gaming/distributed_server
docker compose up -d --build

2. Check Running Containers

Bash / Terminal
Copy
docker compose ps

You will see 6 containers running:

• mc-load-balancer (Gateway on 0.0.0.0:8800->8800/tcp)
• mc-catalog-service-1 (Web & Catalog worker)
• mc-catalog-service-2 (Web & Catalog replica)
• mc-node-service-1 (Node Sync & Storage watchdog)
• mc-node-service-2 (Node Sync replica)
• mc-library-tunnel (Cloudflare Tunnel for remote access)

3. Monitor Live Logs

Bash / Terminal
Copy
# Combined cluster logs:
docker compose logs -f

# Inspect specific service logs:
docker compose logs -f load_balancer
docker compose logs -f catalog_service_1
docker compose logs -f node_service_1

4. Test Health & Live Cluster HUD

Bash / Terminal
Copy
# Cluster Health:
curl http://localhost:8800/health

# Cluster Live Routing Status & Real-Time Pool Stats:
curl http://localhost:8800/cluster/status

5. Stop or Restart Cluster

Bash / Terminal
Copy
# Restart cluster:
docker compose restart

# Stop and tear down all containers cleanly:
docker compose down

---

🎮 Running & Simulating Library Node Daemons

To connect your local PC and populate game_installations:

1. Ensure the server cluster is running on port 8800 (via docker compose or python run_cluster.py).
2. Launch the node daemon pointing to your game directories:

   Bash / Terminal
   Copy
   cd Gaming/distributed_node
   python run_node.py --server http://localhost:8800 --name "Primary-Gaming-PC" --scan "C:\Program Files (x86)\Steam\steamapps\common" "D:\Games"

3. To simulate a multi-computer setup on the same machine, open a second terminal:

   Bash / Terminal
   Copy
   python run_node.py --server http://localhost:8800 --name "Secondary-Laptop" --scan "E:\EpicGames"

4. The daemons will:
   • Register with POST /api/nodes/register (generates an auth token saved in node_config.json).
   • Transmit real disk space usage (total, used, free).
   • Scan your game folders and send installed manifests to POST /api/nodes/{id}/sync.
   • Populate the game_installations, library_nodes, and node_scan_paths tables in Supabase in real-time!