zwitschi/rail-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: correct grammar and formatting in README

Browse Source
This commit is contained in:
zwitschi
2025-10-11 21:37:01 +02:00
parent 8877380f21
commit 0b84ee953e
1 changed files with 147 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

313
README.md
View File

@@ -1,221 +1,204 @@
# Rail Game
A browser-based railway simulation game using real world railway maps from OpenStreetMap.
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 the demo network snapshot
- Build and manage your own railway network
- Dynamic train schedules
- 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
## Architecture
## Current project layout
The project is built using the following technologies:
This repository contains a full-stack demo app (frontend + backend), supporting scripts, docs and infra. Key folders:
- Frontend: HTML5, CSS3, JavaScript, React
- Backend: Python, FastAPI, Flask, SQLAlchemy
- Database: PostgreSQL with PostGIS extension
- Mapping: Leaflet, OpenStreetMap
- `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.
## 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/`.
Refer to the in-repo `docs/` for architecture decisions and deeper design notes.
## Installation
1. Clone the repository:
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
```bash
git clone https://github.com/zwitschi/rail-game.git
cd rail-game
```
2. Set up the backend (from the project root):
### Backend: create virtual environment and install
PowerShell
```bash
python -m venv .venv
.\.venv\Scripts\activate
.\.venv\Scripts\Activate.ps1
python -m pip install -e .[dev]
```
3. Set up the frontend:
Bash / macOS / Linux
```bash
cd frontend
npm install
cd ..
```
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
4. Copy the sample environment file and adjust the database URLs per environment:
### Notes
```bash
copy .env.example .env # PowerShell: Copy-Item .env.example .env
```
- Installing editable extras (`.[dev]`) installs dev/test tools used by the backend (pytest, black, isort, alembic, etc.).
`DATABASE_URL`, `TEST_DATABASE_URL`, and `ALEMBIC_DATABASE_URL` control the runtime, test, and migration connections respectively.
### Environment file
5. (Optional) Point Git to the bundled hooks: `pwsh scripts/setup_hooks.ps1`.
Copy the sample `.env.example` to `.env` and adjust the database connection strings as needed.
6. Run database migrations to set up the schema:
PowerShell
```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:
Bash
- `DATABASE_URL`, `TEST_DATABASE_URL`, and `ALEMBIC_DATABASE_URL` control the runtime, test, and migration connections respectively.
cp .env.example .env
15. (Optional) Point Git to the bundled hooks: `pwsh scripts/setup_hooks.ps1`.
### Important environment variables
16. Run database migrations to set up the schema:
- `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
```bash
cd backend
alembic upgrade head
cd ..
```
17. Refresh OpenStreetMap fixtures (stations + tracks) into the local database:
If you prefer to run alembic with a specific URL without editing `.env`, set `ALEMBIC_DATABASE_URL` in the environment before running the command.
```bash
### 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
```
- Use `--no-commit` to dry-run the loader against existing data, or skip specific steps with the `--skip-*` flags.
See `backend/scripts/*.py` for more granular import options (`--skip-*` flags).
18. Start the development servers from separate terminals:
### Frontend
- Backend: `uvicorn backend.app.main:app --reload --port 8000`
- Frontend: `cd frontend && npm run dev`
Install dependencies and run the dev server from the `frontend/` directory.
19. Open your browser: frontend runs at `http://localhost:5173`, backend API at `http://localhost:8000`.
20. Run quality checks:
PowerShell / Bash
- 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`
cd frontend
npm install
npm run dev
21. Build for production:
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).
- Frontend bundle: `cd frontend && npm run build`
- Backend container: `docker build -t rail-game-backend backend/`
### Run backend locally (development)
22. Run containers:
PowerShell / Bash
- Backend: `docker run -p 8000:8000 rail-game-backend`
- Frontend: Serve `frontend/dist` with any static file host.
# from project root
uvicorn backend.app.main:app --reload --port 8000
## Database Migrations
The backend API listens at `http://localhost:8000` by default.
- 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.
### Tests & linters
## PostgreSQL Configuration
Backend
- **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.
pytest
black backend/ && isort backend/
## API Preview
Frontend
- `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.
cd frontend
npm run lint
npm run build # type/build check
## Developer Tooling
### Docker / Compose (optional)
- 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.
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.