Architecture Diagram

System Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              KUBERNETES CLUSTER                              │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         INGRESS (NGINX)                              │   │
│  │                    galaxy.example.com                                │   │
│  └──────────┬───────────────────┬───────────────────┬──────────────────┘   │
│             │                   │                   │                       │
│             ▼                   ▼                   ▼                       │
│  ┌──────────────────┐ ┌─────────────────┐ ┌─────────────────┐              │
│  │   web-client     │ │  api-gateway    │ │ admin-dashboard │              │
│  │   (static)       │ │  (REST + WS)    │ │   (web UI)      │              │
│  │                  │ │                 │ │                 │              │
│  │  - Three.js      │ │  - /api/*       │ │  - /admin/*     │              │
│  │  - Cockpit UI    │ │  - /ws          │ │  - Metrics      │              │
│  │  - HUD           │ │  - Auth         │ │  - Controls     │              │
│  └──────────────────┘ └────────┬────────┘ └────────┬────────┘              │
│                                │                   │                       │
│             ┌──────────────────┴───────────────────┘                       │
│             │                                                              │
│             ▼                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        GAME SERVICES                                 │   │
│  │                                                                     │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │   │
│  │  │ tick-engine │  │   physics   │  │   players   │  │   galaxy   │ │   │
│  │  │             │  │             │  │             │  │            │ │   │
│  │  │ - Tick loop │  │ - N-body    │  │ - Auth      │  │ - Bodies   │ │   │
│  │  │ - Timing    │  │ - Ships     │  │ - Accounts  │  │ - Config   │ │   │
│  │  │ - Catch-up  │  │ - Leapfrog  │  │ - Sessions  │  │ - Ephemeris│ │   │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────┬──────┘ │   │
│  │         │                │                │               │        │   │
│  └─────────┼────────────────┼────────────────┼───────────────┼────────┘   │
│            │                │                │               │            │
│            ▼                ▼                ▼               ▼            │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        DATA LAYER                                    │   │
│  │                                                                     │   │
│  │  ┌─────────────────────────────┐  ┌──────────────────────────────┐ │   │
│  │  │          REDIS              │  │        POSTGRESQL            │ │   │
│  │  │                             │  │                              │ │   │
│  │  │  - Real-time state          │  │  - Player accounts           │ │   │
│  │  │    • Body positions         │  │  - State snapshots           │ │   │
│  │  │    • Ship positions         │  │  - Admin accounts            │ │   │
│  │  │    • Ship velocities        │  │  - Game configuration        │ │   │
│  │  │  - Event streams            │  │                              │ │   │
│  │  │                             │  │                              │ │   │
│  │  └─────────────────────────────┘  └──────────────────────────────┘ │   │
│  │                                                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

                              ┌─────────────┐
                              │  admin-cli  │
                              │  (kubectl   │
                              │   exec)     │
                              └─────────────┘

Data Flow

Tick Processing

┌────────────┐     1. Trigger      ┌─────────────┐
│tick-engine │ ──────────────────► │   physics   │
│            │                     │             │
│ tick_rate  │     2. Update       │ - Gravity   │
│ = 1 Hz     │ ◄────────────────── │ - Movement  │
└─────┬──────┘     positions       │ - Rotation  │
      │                            └─────────────┘
      │ 3. tick.completed
      ▼
┌─────────────┐     4. Broadcast   ┌─────────────┐
│    Redis    │ ──────────────────►│ api-gateway │
│   Streams   │     state          │             │
└─────────────┘                    └──────┬──────┘
                                          │
                                   5. WebSocket
                                          │
                                          ▼
                                   ┌─────────────┐
                                   │ web-client  │
                                   │  (browser)  │
                                   └─────────────┘

Player Commands

┌─────────────┐  1. Input     ┌─────────────┐  2. Validate   ┌─────────────┐
│ web-client  │ ───────────►  │ api-gateway │ ─────────────► │   players   │
│             │  (WebSocket)  │             │                │             │
└─────────────┘               └─────────────┘                └──────┬──────┘
                                                                    │
                              ┌─────────────┐  3. Update     ┌──────▼──────┐
                              │   physics   │ ◄───────────── │    Redis    │
                              │             │  ship state    │             │
                              └─────────────┘                └─────────────┘

Service Ports

Service	Internal Port	Protocol
api-gateway	8000	HTTP/WS
web-client	80	HTTP
admin-dashboard	8080	HTTP
tick-engine	8001	gRPC
physics	8002	gRPC
players	8003	gRPC
galaxy	8004	gRPC
PostgreSQL	5432	TCP
Redis	6379	TCP

Container Images

Service	Base Image
Python services	python:3.12-slim
web-client	nginx:alpine
PostgreSQL	postgres:16-alpine
Redis	redis:7-alpine