Ironreach MVP

Ironreach is a browser-based multiplayer territory game that mixes real-time map control with army pressure. The monorepo contains a React + PixiJS client, a Go matchmaking gateway, a Go real-time simulation server, shared protobuf-compatible networking code, and Docker infrastructure.

Install

Prerequisites:

• Docker
• Docker Compose

Optional local development prerequisites:

• Node.js 20+
• Go 1.22+

Run Locally

Start the full stack:

docker compose up --build

Endpoints:

• Web client: http://localhost:3000
• Matchmaking gateway: http://localhost:8080
• Game server WebSocket: ws://localhost:8081/ws
• Prometheus: http://localhost:9095

Architecture Overview

apps/web

• React + TypeScript frontend
• PixiJS scene graph renderer
• Binary WebSocket client using protobuf-compatible codecs
• Lobby flow, minimap, leaderboard, split action, and camera follow

apps/gateway

• Go HTTP service
• POST /matchmake selects an available room from Redis
• Prometheus metrics and health endpoint

apps/game-server

• Go WebSocket simulation server
• In-memory rooms capped at 50 players
• 20 TPS game loop
• Spatial hashing grid for nearby queries
• Territory production, powerups, combat, splitting, and leaderboard sync

packages/protocol

• .proto schema
• Handwritten protobuf binary codecs for TypeScript and Go

packages/game-core

• Shared frontend game constants and helpers

infra/docker

• Prometheus scrape configuration

Scaling Suggestions

• Run multiple game-server replicas behind service discovery and publish room heartbeats into Redis with instance identity.
• Move room placement into the gateway or a dedicated allocator service to support geographic routing and autoscaling.
• Persist player sessions, analytics, and ranked snapshots in PostgreSQL or ClickHouse.
• Use Kafka or NATS for cross-region leaderboard aggregation.
• Add edge WebSocket termination and DDoS protection in front of the gateway and simulation layer.