tobymao/18xx

Purpose and Entry Points

18xx.games is a Ruby application for playing many asynchronous 18xx board-game titles online. Rack starts the server through config.ru; HTTP/API wiring is rooted in api.rb, with game and user routes under routes/game.rb and routes/user.rb. The client application is Ruby-rendered through assets/app/app.rb.

Application Boundary and Persistence

The web layer manages authentication, users, sessions, game creation, and game lifecycle separately from deterministic game rules. Database access/models are in db.rb, models/game.rb, and models/action.rb; migrations define the PostgreSQL schema in migrate/0001_initial.rb. Persisted games retain action history, enabling reconstruction, undo/redo, and replay rather than treating the engine as a transient request-only state.

Game Management and Action Flow

assets/app/game_manager.rb is the client-side coordinator for loading games and submitting interactions. Server-side game routes receive actions, while lib/engine/action.rb and concrete action classes such as lib/engine/action/lay_tile.rb represent serializable player commands. The engine validates and applies actions against the current round/step, updates state and logs, then the persisted state/action stream is returned to clients.

Shared Rules Engine

lib/engine.rb is the core domain entry point. lib/engine/game/base.rb supplies common game state and lifecycle behavior; domain objects such as lib/engine/corporation.rb and lib/engine/tile.rb model economic and map state. Generic round orchestration (lib/engine/round/operating.rb) delegates legal decisions and mutations to reusable steps (lib/engine/step/track.rb, lib/engine/step/buy_train.rb). This is the primary boundary: UI and database code should not encode rules.

Title Implementations

Each title is a specialization of the shared engine, normally defining metadata, entities, map, and a game class under lib/engine/game/<title>/. For example, lib/engine/game/g_1846/game.rb, lib/engine/game/g_1846/entities.rb, and lib/engine/game/g_1846/map.rb. Title-specific steps override or extend shared mechanics, e.g. lib/engine/game/g_1817/step/loan.rb. The loader/registry boundary is represented by lib/engine/game.rb and assets/app/game_class_loader.rb.

Client Rendering

The frontend is a Ruby component tree, not a separate JavaScript SPA. assets/app/view/game.rb composes game screens; assets/app/view/game/game_data.rb bridges engine state into renderable data; map visuals are assembled in assets/app/view/game/map.rb and tile-part components such as assets/app/view/game/part/track.rb. User gestures select legal engine actions; rendering reflects the authoritative server game state.

Runtime and Infrastructure

The system is containerized with application, PostgreSQL, Redis, and nginx components: Dockerfile, db/Dockerfile, redis/Dockerfile, and nginx/nginx.conf; Compose definitions include docker-compose.prod.yml. Redis-backed messaging/queue concerns are indicated by lib/bus.rb and queue.rb. Unicorn configuration is at config/unicorn.rb; New Relic configuration exists at config/newrelic.yml. Mail flows for verification, resets, and turn notifications live in assets/app/mail/.