rail-game/README.md

# Rail Game

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

## Features

1. Clone the repository:

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

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

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

3. Set up the frontend:

   ```bash
   cd frontend
   npm install
   cd ..
   ```

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

   ```bash
   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:

   ```bash
   cd backend
   alembic upgrade head
   cd ..
   ```

7. Refresh OpenStreetMap fixtures (stations + tracks) into the local database:

   ```bash
   python -m backend.scripts.osm_refresh --region all
   ```

   Use `--no-commit` to dry-run the loader against existing data, or skip specific steps with the `--skip-*` flags.

8. Start the development servers from separate terminals:

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

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

10. 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`

11. Build for production:

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

12. Run containers:

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

````

11. Build for production:

```bash
copy .env.example .env  # PowerShell: Copy-Item .env.example .env
12. Run containers:

`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:

```bash
cd backend
alembic upgrade head
cd ..
````

7. Refresh OpenStreetMap fixtures (stations + tracks) into the local database:

   ```bash
   python -m backend.scripts.osm_refresh --region all
   ```

   Use `--no-commit` to dry-run the loader against existing data, or skip specific steps with the `--skip-*` flags.

8. Start the development servers from separate terminals:

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

9. Open your browser: frontend runs at `http://localhost:5173`, backend API at `http://localhost:8000`.
10. 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`

11. Build for production:

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

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