fix: revert README structure
This commit is contained in:
149
README.md
149
README.md
@@ -4,6 +4,56 @@ A browser-based railway simulation game using real world railway maps from OpenS
|
|||||||
|
|
||||||
## Features
|
## 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:
|
1. Clone the repository:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
@@ -62,72 +112,83 @@ A browser-based railway simulation game using real world railway maps from OpenS
|
|||||||
|
|
||||||
10. Run quality checks:
|
10. Run quality checks:
|
||||||
|
|
||||||
- Backend unit tests: `pytest`
|
- Backend unit tests: `pytest`
|
||||||
- Backend formatters: `black backend/` and `isort backend/`
|
- Backend formatters: `black backend/` and `isort backend/`
|
||||||
- Frontend lint: `cd frontend && npm run lint`
|
- Frontend lint: `cd frontend && npm run lint`
|
||||||
- Frontend type/build check: `cd frontend && npm run build`
|
- Frontend type/build check: `cd frontend && npm run build`
|
||||||
|
|
||||||
11. Build for production:
|
11. Build for production:
|
||||||
|
|
||||||
- Frontend bundle: `cd frontend && npm run build`
|
- Frontend bundle: `cd frontend && npm run build`
|
||||||
- Backend container: `docker build -t rail-game-backend backend/`
|
- Backend container: `docker build -t rail-game-backend backend/`
|
||||||
|
|
||||||
12. Run containers:
|
12. Run containers:
|
||||||
|
|
||||||
- Backend: `docker run -p 8000:8000 rail-game-backend`
|
- Backend: `docker run -p 8000:8000 rail-game-backend`
|
||||||
- Frontend: Serve `frontend/dist` with any static file host.
|
- Frontend: Serve `frontend/dist` with any static file host.
|
||||||
cd frontend
|
|
||||||
npm install
|
|
||||||
cd ..
|
|
||||||
|
|
||||||
````
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
cd ..
|
||||||
|
```
|
||||||
|
|
||||||
11. Build for production:
|
13. Build for production:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
copy .env.example .env # PowerShell: Copy-Item .env.example .env
|
copy .env.example .env
|
||||||
12. Run containers:
|
```
|
||||||
|
|
||||||
`DATABASE_URL`, `TEST_DATABASE_URL`, and `ALEMBIC_DATABASE_URL` control the runtime, test, and migration connections respectively.
|
- PowerShell:
|
||||||
5. (Optional) Point Git to the bundled hooks: `pwsh scripts/setup_hooks.ps1`.
|
|
||||||
6. Run database migrations to set up the schema:
|
|
||||||
|
|
||||||
```bash
|
```pwsh
|
||||||
cd backend
|
Copy-Item .env.example .env
|
||||||
alembic upgrade head
|
```
|
||||||
cd ..
|
|
||||||
````
|
|
||||||
|
|
||||||
7. Refresh OpenStreetMap fixtures (stations + tracks) into the local database:
|
14. Run containers:
|
||||||
|
|
||||||
```bash
|
- `DATABASE_URL`, `TEST_DATABASE_URL`, and `ALEMBIC_DATABASE_URL` control the runtime, test, and migration connections respectively.
|
||||||
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.
|
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`
|
```bash
|
||||||
- Frontend: `cd frontend && npm run dev`
|
cd backend
|
||||||
|
alembic upgrade head
|
||||||
|
cd ..
|
||||||
|
```
|
||||||
|
|
||||||
9. Open your browser: frontend runs at `http://localhost:5173`, backend API at `http://localhost:8000`.
|
17. Refresh OpenStreetMap fixtures (stations + tracks) into the local database:
|
||||||
10. Run quality checks:
|
|
||||||
|
|
||||||
- Backend unit tests: `pytest`
|
```bash
|
||||||
- Backend formatters: `black backend/` and `isort backend/`
|
python -m backend.scripts.osm_refresh --region all
|
||||||
- Frontend lint: `cd frontend && npm run lint`
|
```
|
||||||
- Frontend type/build check: `cd frontend && npm run build`
|
|
||||||
|
|
||||||
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`
|
18. Start the development servers from separate terminals:
|
||||||
- Backend container: `docker build -t rail-game-backend backend/`
|
|
||||||
|
|
||||||
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`
|
19. Open your browser: frontend runs at `http://localhost:5173`, backend API at `http://localhost:8000`.
|
||||||
- Frontend: Serve `frontend/dist` with any static file host.
|
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
|
## Database Migrations
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user