# 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 starts all services (Postgres, Redis, backend, frontend) and automatically initializes the database with demo data on first run. The backend waits for the database to be ready before running migrations and loading OSM fixtures.

**Services:**

- Backend API: `http://localhost:8000`
- Frontend: `http://localhost:8080`
- Postgres: `localhost:5432`
- Redis: `localhost:6379`

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.