🏗️ FireMUD System Architecture: Overview

This document provides a high-level view of FireMUD’s system architecture, showing how major services, protocols, and data flows interact across the platform.

🧩 Core Architecture Principles

• Microservices-based domain-driven architecture with clearly separated responsibilities
• Spring Cloud Gateway serves as the unified HTTP/WebSocket entry point for all clients
• TCP Proxy Service accepts Telnet connections and upgrades them to WebSocket for the Gateway
• Consistent end-to-end WebSocket flow: Telnet (TCP) → TCP Proxy Service (WebSocket upgrade) → Spring Cloud Gateway → Game Session Service
• All client traffic is routed through the Spring Cloud Gateway, ensuring centralized traffic routing, monitoring, and observability. See Gateway Architecture for deployment details and stateless behavior.

  🛑 Gameplay login is handled by the Game Session Service — the Gateway may validate JWTs for admin endpoints, but gameplay clients connect without tokens. See Authentication & Authorization for the full login flow.

• Telnet clients maintain sticky TCP connections only to the TCP Proxy Service, which buffers active input, but discards it across reconnects
• Reconnection logic is handled in layers to preserve gameplay continuity
• All internal service-to-service communication from the Game Session Service onward uses gRPC, with strict schema enforcement and low latency
• Session state is stored in Redis to keep services stateless and support gameplay recovery
• Game definitions and rules are data-driven and editable via tooling without redeploying code
• Game Session Service orchestrates live game instances, including tick execution and runtime configuration
• Feature flags are defined at design-time in the Game Design Service and toggled at runtime by the Game Session Service
• 🔁 One session per character is allowed — logging in from another client forcibly transfers control to the new session and terminates the old one

🖼️ See also: System Architecture Diagram and System Context Diagram

🔁 Reconnection Strategy

FireMUD supports seamless gameplay recovery through a layered reconnection model:

🔗 See Reconnection Strategy for full details on session resumption, reauthentication, and failure handling.

🔗 Major Components and Their Roles

🌐 Communication Flows

✅ All internal communication from the Game Session Service onward uses gRPC with strict schema enforcement.

📦 Data and State Management

• Persistent data (accounts, entities, rooms) is stored in PostgreSQL by domain-aligned services
• Volatile state (sessions, command queues, timers) is stored in Redis and coordinated by the Game Session Service
• Redis is a non-authoritative coordination buffer — but critical for consistency, ticks, retries, and recovery
• Tick regions are shard-aligned in Redis to preserve atomicity

📌 See Redis Architecture for key structure and durability strategies.

⏱️ Game Loop / Tick Model

FireMUD uses a Hybrid Tick Model to balance responsiveness and fairness:

• One action per entity per tick (pulled from command queues)
• Region-scoped ticks execute independently for parallelism
• Tick state (locks, queues, timers) is stored and coordinated via Redis

🔗 Tick execution, staging/rollback, retry policies, and crash recovery are detailed in Tick System and Runtime Design

🔐 Authentication and Authorization Flow

Clients authenticate using the LOGIN command, processed by the Game Session Service. On disconnect, clients must reauthenticate to resume gameplay. Session state is stored in Redis and reused for recovery.

🔗 See Authentication & Authorization for JWT format and session flow.

📊 Observability and Monitoring

See Logging & Monitoring for the full pipeline, including Fluent Bit, Prometheus, and related dashboards.

🔗 Additional Redis metrics are noted in Redis Architecture.

🗂️ Deployment Layers

Deployment health checks (readiness and liveness probes) for these layers are described in detail in Deployment Environments.

Environment-specific routing is configured through Spring profiles (application-dev.yml, application-prod.yml). See Deployment Environments for how these profiles differ in Docker Compose versus Kubernetes.

🔎 Notes on Responsibility Alignment

• Functional responsibilities are defined in the Service Responsibility Matrix
• Game Session Service orchestrates tick lifecycles, retries, and session management
• Game Logic Service resolves individual actions deterministically based on input state
• Redis acts as a passive, high-speed execution substrate — storing volatile state and enabling atomic coordination via Lua scripts

🧠 Why Game Session Service vs Game Logic Service? Game Logic Service is stateless and deterministic. Game Session Service governs pacing, conflict handling, and orchestration across distributed tick regions.

📚 Related Documentation

Diagrams

• System Architecture Diagram
• System Context Diagram

Infrastructure & Deployment

• Infrastructure Overview
• Deployment Environments
• Gateway Architecture
• Protocol Bridging
• Multi-Tenancy Architecture

Runtime & Security

• Redis Architecture
• Tick System and Runtime Design
• Reconnection Strategy
• Authentication & Authorization
• Security Architecture
• Logging & Monitoring
• Database Migrations
• Testing Strategy

Responsibilities

• Microservices Responsibility Matrix