zwitschi
615b63ba76
- Introduced unit tests for the station service, covering creation, updating, and archiving of stations. - Added detailed building block view documentation outlining the architecture of the Rail Game system. - Created runtime view documentation illustrating key user interactions and system behavior. - Developed concepts documentation detailing domain models, architectural patterns, and security considerations. - Updated architecture documentation to reference new detailed sections for building block and runtime views.
5.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 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.5 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.6 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