rail-game/README.md

Rail Game

A browser-based railway simulation game using real-world railway maps from OpenStreetMap.

At a glance

• Frontend: React + Vite (TypeScript)
• Backend: Python (FastAPI, SQLAlchemy)
• Database: PostgreSQL with PostGIS (spatial types)
• Mapping: Leaflet + OpenStreetMap

Features

• Real-world railway maps
• Interactive Leaflet map preview of a demo network snapshot
• Build and manage your railway network
• Dynamic train schedules and simulated trains

Current project layout

This repository contains a full-stack demo app (frontend + backend), supporting scripts, docs and infra. Key folders:

• backend/ — FastAPI application, models, services, migration scripts and backend tests.
• frontend/ — React app (Vite) and frontend tests.
• docs/ — Architecture docs and ADRs.
• infra/ — Deployment assets (Dockerfiles, compose files, init scripts).
• data/ — Fixtures and imported OSM snapshots.
• scripts/ — Utility scripts (precommit helpers, setup hooks).
• tests/ — End-to-end tests and cross-cutting tests.

Refer to the in-repo docs/ for architecture decisions and deeper design notes.

Installation

Below are concise, verified steps for getting the project running locally. Commands show both PowerShell (Windows) and Bash/macOS/Linux variants where they differ.

Prerequisites

• Git
• Python 3.10+ (3.11 recommended) and pip
• Node.js 16+ (or the version required by frontend/package.json)
• PostgreSQL with PostGIS if you want to run the full DB-backed stack locally
• Docker & Docker Compose (optional, for containerized dev)

Clone repository

PowerShell / Bash

git clone https://github.com/zwitschi/rail-game.git
cd rail-game

Backend: create virtual environment and install

PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .[dev]

Bash / macOS / Linux

python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

Notes

• Installing editable extras (.[dev]) installs dev/test tools used by the backend (pytest, black, isort, alembic, etc.).

Environment file

Copy the sample .env.example to .env and adjust the database connection strings as needed.

PowerShell

Copy-Item .env.example .env

Bash

cp .env.example .env

Important environment variables

• DATABASE_URL — runtime DB connection for the app
• TEST_DATABASE_URL — database used by pytest in CI/local tests
• ALEMBIC_DATABASE_URL — used when running alembic outside the app process

Database (Postgres + PostGIS)

If you run Postgres locally, create the dev/test DBs and ensure the postgis extension is available. Example (psql):

-- create DBs (run in psql as a superuser or role with create privileges)
CREATE DATABASE railgame_dev;
CREATE DATABASE railgame_test;

-- connect to the db and enable extensions
\c railgame_dev
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS pgcrypto;

Adjust DB names and roles to match your .env values.

Quick database setup (recommended)

For a streamlined setup, use the included initialization script after configuring your .env file:

PowerShell / Bash

python scripts/init_demo_db.py

This script validates your environment, runs migrations, and loads demo OSM data. Use --dry-run to preview changes, or --region to load specific regions.

Note: The script uses python-dotenv to load your .env file. If not installed, run pip install python-dotenv.

Run migrations

PowerShell / Bash

cd backend
alembic upgrade head
cd ..

If you prefer to run alembic with a specific URL without editing .env, set ALEMBIC_DATABASE_URL in the environment before running the command.

Load OSM fixtures (optional)

Use the included scripts to refresh stations and tracks from saved OSM fixtures. This step assumes the database is migrated and reachable.

PowerShell / Bash

# dry-run
python -m backend.scripts.osm_refresh --region all --no-commit

# commit to DB
python -m backend.scripts.osm_refresh --region all

See backend/scripts/*.py for more granular import options (--skip-* flags).

Frontend

Install dependencies and run the dev server from the frontend/ directory.

PowerShell / Bash

cd frontend
npm install
npm run dev

The frontend runs at http://localhost:5173 by default (Vite). The React app talks to the backend API at the address configured in its environment (see frontend README or vite config).

Run backend locally (development)

PowerShell / Bash

# from project root
uvicorn backend.app.main:app --reload --port 8000

The backend API listens at http://localhost:8000 by default.

Tests & linters

Backend

pytest
black backend/ && isort backend/

Frontend

cd frontend
npm run lint
npm run build    # type/build check

Docker / Compose (optional)

Build and run both services with Docker Compose if you prefer containers:

PowerShell / Bash

docker compose up --build

This expects a working Docker environment and may require you to set DB URLs to point to the containerized Postgres service if one is defined in docker-compose.yml.

Troubleshooting

• If migrations fail with missing PostGIS functions, ensure postgis is installed and enabled in the target database.
• If alembic autogenerate creates unexpected changes, confirm the models being imported match the app import path used by alembic (see backend/migrations/env.py).
• For authentication/debugging, the demo user is demo / railgame123 (used by some integration tests and the demo auth flow).
• If frontend dev server fails due to node version, check frontend/package.json engines or use nvm/nvm-windows to match the recommended Node version.

API preview

Some useful endpoints for local testing:

• GET /api/health — readiness probe
• POST /api/auth/register — demo account creation + JWT
• POST /api/auth/login — exchange credentials for JWT (demo user: demo / railgame123)
• GET /api/auth/me — current user profile (requires bearer token)
• GET /api/network — sample network snapshot (requires bearer token)

Contributing

• See docs/ for architecture and ADRs.
• Keep tests green and follow formatting rules (black, isort for Python; Prettier/ESLint for frontend).
• Open issues or PRs for bugs, features, or docs improvements.