# 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.