Rail Game

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

Features

• Real world railway maps
• Interactive Leaflet map preview of the demo network snapshot
• Build and manage your own railway network
• Dynamic train schedules

Architecture

The project is built using the following technologies:

• Frontend: HTML5, CSS3, JavaScript, React
• Backend: Python, FastAPI, Flask, SQLAlchemy
• Database: PostgreSQL with PostGIS extension
• Mapping: Leaflet, OpenStreetMap

Project Structure

Planned structure for code and assets (folders created as needed):

rail-game/
|-- backend/
|   |-- app/
|   |   |-- api/            # FastAPI/Flask route handlers
|   |   |-- core/           # Config, startup, shared utilities
|   |   |-- models/         # SQLAlchemy models and schemas
|   |   |-- services/       # Domain logic and service layer
|   |   `-- websocket/      # Real-time communication handlers
|   |-- tests/              # Backend unit and integration tests
|   `-- requirements/       # Backend dependency lockfiles
|-- frontend/
|   |-- public/             # Static assets served as-is
|   |-- src/
|   |   |-- components/     # Reusable React components
|   |   |-- hooks/          # Custom React hooks
|   |   |-- pages/          # Top-level routed views
|   |   |-- state/          # Redux/Context stores and slices
|   |   |-- styles/         # Global and modular stylesheets
|   |   `-- utils/          # Frontend helpers and formatters
|   `-- tests/              # Frontend unit and integration tests
|-- docs/                   # Architecture docs, ADRs, guides
|-- infra/                  # Deployment, IaC, Docker, CI workflows
|-- scripts/                # Tooling for setup, linting, migrations
|-- data/                   # Seed data, fixtures, import/export tooling
`-- tests/                  # End-to-end and cross-cutting tests

Use infra/ to capture deployment assets (Dockerfiles, compose files, Terraform) and .github/ for automation. Shared code that crosses layers should live in the respective service directories or dedicated packages under backend/.

Installation

1. Clone the repository:

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

2. Set up the backend (from the project root):

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

3. Set up the frontend:

   cd frontend
   npm install
   cd ..
   

4. Copy the sample environment file and adjust the database URLs per environment:

   copy .env.example .env  # PowerShell: Copy-Item .env.example .env
   

   DATABASE_URL, TEST_DATABASE_URL, and ALEMBIC_DATABASE_URL control the runtime, test, and migration connections respectively.

5. (Optional) Point Git to the bundled hooks: pwsh scripts/setup_hooks.ps1.

6. Run database migrations to set up the schema:

   cd backend
   alembic upgrade head
   cd ..
   

7. Start the development servers from separate terminals:

   • Backend: uvicorn backend.app.main:app --reload --port 8000
   • Frontend: cd frontend && npm run dev

8. Open your browser: frontend runs at http://localhost:5173, backend API at http://localhost:8000.

9. Run quality checks:

   • Backend unit tests: pytest
   • Backend formatters: black backend/ and isort backend/
   • Frontend lint: cd frontend && npm run lint
   • Frontend type/build check: cd frontend && npm run build

10. Build for production:

    • Frontend bundle: cd frontend && npm run build
    • Backend container: docker build -t rail-game-backend backend/

11. Run containers:

    • Backend: docker run -p 8000:8000 rail-game-backend
    • Frontend: Serve frontend/dist with any static file host.

Database Migrations

• Alembic configuration lives in backend/alembic.ini with scripts under backend/migrations/.
• Generate new revisions with alembic revision --autogenerate -m "short description" (ensure models are imported before running autogenerate).
• Apply migrations via alembic upgrade head; rollback with alembic downgrade -1 during development.

PostgreSQL Configuration

• Database URLs: The backend reads connection strings from the .env file. Set DATABASE_URL (development), TEST_DATABASE_URL (pytest/CI), and ALEMBIC_DATABASE_URL (migration runner). URLs use the SQLAlchemy format, e.g. postgresql+psycopg://user:password@host:port/database.
• Required Extensions: Migrations enable postgis for spatial types and pgcrypto for UUID generation. Ensure your Postgres instance has these extensions available.
• Recommended Databases: create railgame_dev and railgame_test (or variants) owned by a dedicated railgame role with privileges to create extensions.
• Connection Debugging: Toggle DATABASE_ECHO=true in .env to log SQL statements during development.

API Preview

• GET /api/health – Lightweight readiness probe.
• POST /api/auth/register – Creates an in-memory demo account and returns a JWT access token.
• POST /api/auth/login – Exchanges credentials for a JWT access token (demo user: demo / railgame123).
• GET /api/auth/me – Returns the current authenticated user profile.
• GET /api/network – Returns a sample snapshot of stations, tracks, and trains (camelCase fields) generated from shared domain models; requires a valid bearer token.

Developer Tooling

• Install backend tooling in editable mode: python -m pip install -e .[dev].
• Configure git hooks (Git for Windows works with these scripts): pwsh scripts/setup_hooks.ps1.
• Pre-commit hooks run black, isort, pytest backend/tests, and npm run lint if frontend dependencies are installed.
• Run the checks manually any time with python scripts/precommit.py.
• Frontend lint/format commands live in frontend/package.json (npm run lint, npm run format).
• Continuous integration runs via workflows in .github/workflows/ covering backend lint/tests and frontend lint/build.