rail-game/docs/06_Runtime_View.md

# 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 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.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.

```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.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.

```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