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.
6.3 KiB
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.
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.
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.
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.
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.
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.
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.
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