feat: Initialize frontend and backend structure with essential configurations
- Added TypeScript build info for frontend. - Created Vite configuration for React application. - Implemented pre-commit hook to run checks before commits. - Set up PostgreSQL Dockerfile with PostGIS support and initialization scripts. - Added database creation script for PostgreSQL with necessary extensions. - Established Python project configuration with dependencies and development tools. - Developed pre-commit script to enforce code quality checks for backend and frontend. - Created PowerShell script to set up Git hooks path.
This commit is contained in:
146
README.md
Normal file
146
README.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Rail Game
|
||||
|
||||
A browser-based railway simulation game using real world railway maps from 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
|
||||
|
||||
## 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
|
||||
git clone https://github.com/zwitschi/rail-game.git
|
||||
cd rail-game
|
||||
```
|
||||
|
||||
2. Set up the backend (from the project root):
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
.\.venv\Scripts\activate
|
||||
python -m pip install -e .[dev]
|
||||
```
|
||||
|
||||
3. Set up the frontend:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
cd ..
|
||||
```
|
||||
|
||||
4. Copy the sample environment file and adjust the database URLs per environment:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
alembic upgrade head
|
||||
cd ..
|
||||
```
|
||||
|
||||
7. Start the development servers from separate terminals:
|
||||
|
||||
- Backend: `uvicorn backend.app.main:app --reload --port 8000`
|
||||
- Frontend: `cd frontend && npm run dev`
|
||||
|
||||
8. Open your browser: frontend runs at `http://localhost:5173`, backend API at `http://localhost:8000`.
|
||||
9. 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`
|
||||
|
||||
10. Build for production:
|
||||
|
||||
- Frontend bundle: `cd frontend && npm run build`
|
||||
- Backend container: `docker build -t rail-game-backend backend/`
|
||||
|
||||
11. 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.
|
||||
Reference in New Issue
Block a user