rail-game/README.md

# 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):

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

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

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

13. Build for production:

    ```bash
    copy .env.example .env
    ```

    - PowerShell:

    ```pwsh
    Copy-Item .env.example .env
    ```

14. Run containers:

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

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

16. Run database migrations to set up the schema:

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

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

18. Start the development servers from separate terminals:

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

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

21. Build for production:

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

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