From 8877380f2186f0f22f066fc53878fb576945596e Mon Sep 17 00:00:00 2001 From: zwitschi Date: Sat, 11 Oct 2025 21:07:27 +0200 Subject: [PATCH] fix: revert README structure --- README.md | 149 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 105 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 4cdf476..b852fb8 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,56 @@ A browser-based railway simulation game using real world railway maps from OpenS ## 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 @@ -62,72 +112,83 @@ A browser-based railway simulation game using real world railway maps from OpenS 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` + - 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/` + - 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 .. + - Backend: `docker run -p 8000:8000 rail-game-backend` + - Frontend: Serve `frontend/dist` with any static file host. -```` + ```bash + cd frontend + npm install + cd .. + ``` -11. Build for production: +13. Build for production: -```bash -copy .env.example .env # PowerShell: Copy-Item .env.example .env -12. Run containers: + ```bash + copy .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: + - PowerShell: -```bash -cd backend -alembic upgrade head -cd .. -```` + ```pwsh + Copy-Item .env.example .env + ``` -7. Refresh OpenStreetMap fixtures (stations + tracks) into the local database: +14. Run containers: - ```bash - python -m backend.scripts.osm_refresh --region all - ``` + - `DATABASE_URL`, `TEST_DATABASE_URL`, and `ALEMBIC_DATABASE_URL` control the runtime, test, and migration connections respectively. - Use `--no-commit` to dry-run the loader against existing data, or skip specific steps with the `--skip-*` flags. +15. (Optional) Point Git to the bundled hooks: `pwsh scripts/setup_hooks.ps1`. -8. Start the development servers from separate terminals: +16. Run database migrations to set up the schema: - - Backend: `uvicorn backend.app.main:app --reload --port 8000` - - Frontend: `cd frontend && npm run dev` + ```bash + cd backend + alembic upgrade head + cd .. + ``` -9. Open your browser: frontend runs at `http://localhost:5173`, backend API at `http://localhost:8000`. -10. Run quality checks: +17. Refresh OpenStreetMap fixtures (stations + tracks) into the local database: -- 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` + ```bash + python -m backend.scripts.osm_refresh --region all + ``` -11. Build for production: + - Use `--no-commit` to dry-run the loader against existing data, or skip specific steps with the `--skip-*` flags. -- Frontend bundle: `cd frontend && npm run build` -- Backend container: `docker build -t rail-game-backend backend/` +18. Start the development servers from separate terminals: -12. Run containers: + - Backend: `uvicorn backend.app.main:app --reload --port 8000` + - Frontend: `cd frontend && npm run dev` -- Backend: `docker run -p 8000:8000 rail-game-backend` -- Frontend: Serve `frontend/dist` with any static file host. +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