zwitschi
c2927f2f60
- Added new fields to TrackModel: status, is_bidirectional, and coordinates. - Updated network service to handle new track attributes and geometry extraction. - Introduced CLI scripts for importing and loading tracks from OpenStreetMap. - Implemented normalization of track elements to ensure valid geometries. - Enhanced tests for track model, network service, and import/load scripts. - Updated frontend to accommodate new track attributes and improve route computation. - Documented OSM ingestion process in architecture and runtime views.
181 lines
6.3 KiB
Markdown
181 lines
6.3 KiB
Markdown
# 6. Runtime View
|
|
|
|
### 6.1 Overview
|
|
|
|
The runtime view illustrates the dynamic behavior of the Rail Game system during typical user interactions. It shows how the building blocks interact to fulfill user requests and maintain system state.
|
|
|
|
### 6.2 Key Runtime Scenarios
|
|
|
|
#### 6.2.1 User Authentication
|
|
|
|
**Scenario**: A user signs up and logs into the game.
|
|
|
|
**Description**: From the authentication UI the user can either register a new profile or sign in with existing credentials. New registrations are persisted in the prototype's in-memory store. On login the backend verifies the credentials and issues a JWT token for subsequent requests.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as User
|
|
participant F as Frontend
|
|
participant B as Backend API
|
|
participant D as Database
|
|
|
|
U->>F: Submit signup/login form
|
|
alt Register new account
|
|
F->>B: POST /api/auth/register
|
|
B->>B: Persist user (in-memory prototype store)
|
|
end
|
|
F->>B: POST /api/auth/login
|
|
B->>D: Query user credentials
|
|
D-->>B: User data
|
|
B->>B: Validate password
|
|
B-->>F: JWT token
|
|
F-->>U: Redirect to dashboard
|
|
```
|
|
|
|
#### 6.2.2 Loading Map and Railway Data
|
|
|
|
**Scenario**: User opens the game and loads their railway network.
|
|
|
|
**Description**: The frontend requests map tiles from OpenStreetMap and user-specific railway data from the backend, which retrieves it from the database.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as User
|
|
participant F as Frontend
|
|
participant B as Backend API
|
|
participant D as Database
|
|
participant OSM as OpenStreetMap
|
|
|
|
U->>F: Open game
|
|
F->>OSM: Request map tiles
|
|
OSM-->>F: Map tiles
|
|
F->>B: GET /api/railways/{userId}
|
|
B->>D: Query user railways
|
|
D-->>B: Railway data (spatial)
|
|
B-->>F: Railway network JSON
|
|
F->>F: Render map with railways
|
|
```
|
|
|
|
#### 6.2.3 Fetching Network Snapshot (current implementation)
|
|
|
|
**Scenario**: The frontend loads a shared snapshot of stations, tracks, and trains using the domain models.
|
|
|
|
**Description**: After the React client authenticates and stores the issued access token, it calls the FastAPI `/api/network` endpoint with a bearer header. The backend constructs a `NetworkSnapshot` using immutable domain models and returns camelCase JSON for direct consumption by TypeScript interfaces. The frontend hydrates both summary lists and the React Leaflet map overlay with the resulting station and track geometry.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant F as Frontend (React)
|
|
participant H as Hook (useNetworkSnapshot)
|
|
participant A as API Router (/api/network)
|
|
participant S as Network Service
|
|
|
|
F->>H: Mount component
|
|
H->>A: GET /api/network (Bearer token)
|
|
A->>S: Build snapshot using domain models
|
|
S-->>A: Stations, tracks, trains (camelCase JSON)
|
|
A-->>H: 200 OK + payload
|
|
H-->>F: Update UI state (loading → success)
|
|
F->>F: Render Leaflet map and snapshot summaries
|
|
```
|
|
|
|
#### 6.2.4 OSM Track Import and Load
|
|
|
|
**Scenario**: Operator refreshes spatial fixtures by harvesting OSM railways and persisting them to PostGIS.
|
|
|
|
**Description**: The paired CLI scripts `tracks_import.py` and `tracks_load.py` export candidate track segments from Overpass, associate endpoints with the nearest known stations, and store the resulting LINESTRING geometries. Dry-run flags allow inspection of the generated Overpass payload or database mutations before commit.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Ops as Operator
|
|
participant TI as tracks_import.py
|
|
participant OL as Overpass API
|
|
participant TL as tracks_load.py
|
|
participant DB as PostGIS
|
|
|
|
Ops->>TI: Invoke with region + output path
|
|
TI->>OL: POST compiled Overpass query
|
|
OL-->>TI: Return rail way elements (JSON)
|
|
TI-->>Ops: Write normalized tracks JSON
|
|
Ops->>TL: Invoke with normalized JSON
|
|
TL->>DB: Fetch stations + existing tracks
|
|
TL->>DB: Insert snapped LINESTRING geometries
|
|
TL-->>Ops: Report committed track count
|
|
```
|
|
|
|
#### 6.2.5 Building Railway Network
|
|
|
|
**Scenario**: User adds a new track segment to their railway network.
|
|
|
|
**Description**: The user interacts with the map to place a new track. The frontend sends the new track data to the backend, which validates and stores it in the database.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as User
|
|
participant F as Frontend
|
|
participant B as Backend API
|
|
participant D as Database
|
|
|
|
U->>F: Draw new track on map
|
|
F->>F: Validate track placement
|
|
F->>B: POST /api/tracks
|
|
B->>B: Validate track logic
|
|
B->>D: Insert new track (spatial)
|
|
D-->>B: Confirmation
|
|
B-->>F: Success response
|
|
F->>F: Update map display
|
|
```
|
|
|
|
#### 6.2.6 Running Train Simulation
|
|
|
|
**Scenario**: User starts a train simulation on their network.
|
|
|
|
**Description**: The frontend requests simulation start, backend calculates train routes and schedules, updates database with simulation state, and sends real-time updates back to frontend.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as User
|
|
participant F as Frontend
|
|
participant B as Backend API
|
|
participant D as Database
|
|
|
|
U->>F: Click "Start Simulation"
|
|
F->>B: POST /api/simulation/start
|
|
B->>D: Query railway network
|
|
D-->>B: Network data
|
|
B->>B: Calculate routes & schedules
|
|
B->>D: Update train positions
|
|
D-->>B: Confirmation
|
|
B-->>F: Simulation started
|
|
loop Real-time updates
|
|
B->>B: Update train positions
|
|
B->>D: Save positions
|
|
B-->>F: WebSocket position updates
|
|
end
|
|
```
|
|
|
|
#### 6.2.7 Saving Game Progress
|
|
|
|
**Scenario**: User saves their current game state.
|
|
|
|
**Description**: The frontend periodically or on user request sends current game state to backend for persistence.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant F as Frontend
|
|
participant B as Backend API
|
|
participant D as Database
|
|
|
|
F->>B: POST /api/save
|
|
B->>D: Update user progress
|
|
D-->>B: Confirmation
|
|
B-->>F: Save successful
|
|
```
|
|
|
|
### 6.3 Performance and Scalability Considerations
|
|
|
|
- **Database Queries**: Spatial queries for railway data are optimized using PostGIS indexes
|
|
- **Caching**: Frequently accessed map tiles and user data may be cached
|
|
- **Real-time Updates**: WebSocket connections for simulation updates, with fallback to polling
|
|
- **Load Balancing**: Backend API can be scaled horizontally for multiple users
|
|
- **CDN**: Static assets and map tiles served via CDN for faster loading
|