From 0b84ee953e755ff11dc0e30c91ef22e5e96736f4 Mon Sep 17 00:00:00 2001 From: zwitschi Date: Sat, 11 Oct 2025 21:37:01 +0200 Subject: [PATCH] fix: correct grammar and formatting in README --- README.md | 311 ++++++++++++++++++++++++++---------------------------- 1 file changed, 147 insertions(+), 164 deletions(-) diff --git a/README.md b/README.md index b852fb8..c5fb210 100644 --- a/README.md +++ b/README.md @@ -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. - ```bash - git clone https://github.com/zwitschi/rail-game.git - cd rail-game - ``` +## Prerequisites -2. Set up the backend (from the project root): +- 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) - ```bash - python -m venv .venv - .\.venv\Scripts\activate - python -m pip install -e .[dev] - ``` +### Clone repository -3. Set up the frontend: +PowerShell / Bash - ```bash - cd frontend - npm install - cd .. - ``` + git clone https://github.com/zwitschi/rail-game.git + cd rail-game -4. Copy the sample environment file and adjust the database URLs per environment: +### Backend: create virtual environment and install - ```bash - copy .env.example .env # PowerShell: Copy-Item .env.example .env - ``` +PowerShell - `DATABASE_URL`, `TEST_DATABASE_URL`, and `ALEMBIC_DATABASE_URL` control the runtime, test, and migration connections respectively. + python -m venv .venv + .\.venv\Scripts\Activate.ps1 + python -m pip install -e .[dev] -5. (Optional) Point Git to the bundled hooks: `pwsh scripts/setup_hooks.ps1`. +Bash / macOS / Linux -6. Run database migrations to set up the schema: + python -m venv .venv + source .venv/bin/activate + python -m pip install -e '.[dev]' - ```bash - cd backend - alembic upgrade head - cd .. - ``` +### Notes -7. Refresh OpenStreetMap fixtures (stations + tracks) into the local database: +- Installing editable extras (`.[dev]`) installs dev/test tools used by the backend (pytest, black, isort, alembic, etc.). - ```bash - python -m backend.scripts.osm_refresh --region all - ``` +### Environment file - Use `--no-commit` to dry-run the loader against existing data, or skip specific steps with the `--skip-*` flags. +Copy the sample `.env.example` to `.env` and adjust the database connection strings as needed. -8. Start the development servers from separate terminals: +PowerShell - - 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.