rail-game/README.md

Rail Game

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

Features

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. Refresh OpenStreetMap fixtures (stations + tracks) into the local database:

   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:

   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.