feat: Enhance track model and import functionality

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

docs/05_Building_Block_View.md

@@ -111,6 +111,7 @@ graph TD
 
 - **Health Module**: Lightweight readiness probes used by infrastructure checks.
 - **Network Module**: Serves read-only snapshots of stations, tracks, and trains using shared domain models (camelCase aliases for client compatibility).
+- **OSM Ingestion CLI**: Script pairings (`stations_import`/`stations_load`, `tracks_import`/`tracks_load`) that harvest OpenStreetMap fixtures and persist normalized station and track geometries into PostGIS.
 - **Authentication Module**: JWT-based user registration, authentication, and authorization. The current prototype supports on-the-fly account creation backed by an in-memory user store and issues short-lived access tokens to validate the client flow end-to-end.
 - **Railway Calculation Module**: Algorithms for route optimization and scheduling (planned).
 - **Resource Management Module**: Logic for game economy and progression (planned).
@@ -157,4 +158,3 @@ rail-game/
 ```
 
 Shared code that spans application layers should be surfaced through well-defined APIs within `backend/app/services` or exposed via frontend data contracts to keep coupling low. Infrastructure automation and CI/CD assets remain isolated under `infra/` to support multiple deployment targets.
-

docs/06_Runtime_View.md

@@ -78,7 +78,31 @@ sequenceDiagram
     F->>F: Render Leaflet map and snapshot summaries
 ```
 
-#### 6.2.4 Building Railway Network
+#### 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.
 
@@ -101,7 +125,7 @@ sequenceDiagram
     F->>F: Update map display
 ```
 
-#### 6.2.5 Running Train Simulation
+#### 6.2.6 Running Train Simulation
 
 **Scenario**: User starts a train simulation on their network.
 
@@ -129,7 +153,7 @@ sequenceDiagram
     end
 ```
 
-#### 6.2.6 Saving Game Progress
+#### 6.2.7 Saving Game Progress
 
 **Scenario**: User saves their current game state.
 
@@ -154,4 +178,3 @@ sequenceDiagram
 - **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
-

docs/architecture.md

@@ -100,6 +100,7 @@ The system interacts with:
 
 - Browser-native implementation for broad accessibility
 - Spatial database for efficient geographical queries
+- Offline-friendly OSM ingestion pipeline that uses dedicated CLI scripts to export/import stations and tracks before seeding the database
 - Modular architecture allowing for future extensions (e.g., multiplayer)
 
 ## 5. Building Block View