# 8. Concepts

### 8.1 Domain Concepts

#### 8.1.1 Railway Network Model

The core domain concept is the railway network, consisting of:

- **Tracks**: Linear segments connecting geographical points, stored as spatial geometries
- **Stations**: Key points on the network where trains can stop, load/unload passengers or cargo
- **Trains**: Movable entities that follow routes along tracks according to schedules
- **Schedules**: Time-based plans for train movements and operations

Railway networks are user-created and managed, built upon real-world geographical data from OpenStreetMap.

#### 8.1.2 Game Economy

Resource management drives gameplay:

- **Currency**: Earned through network operations and achievements
- **Resources**: Required for building and upgrading railway components
- **Scoring**: Based on network efficiency, passenger satisfaction, and operational success

#### 8.1.3 Simulation Engine

Dynamic simulation of train operations:

- **Route Calculation**: Pathfinding algorithms to determine optimal train routes
- **Schedule Optimization**: Balancing train frequencies with network capacity
- **Real-time Updates**: Live position tracking and status reporting

#### 8.1.4 Network Snapshot Contract

- **Shared Models**: The backend uses immutable Pydantic models with camelCase aliases that mirror TypeScript interfaces in `frontend/src/types/domain.ts`.
- **Snapshot Service**: Until persistence exists, a service synthesises demo stations, tracks, and trains to keep the client workflow functional.
- **Client Hook**: `useNetworkSnapshot` orchestrates fetch status (idle/loading/success/error) and pushes data into the React view layer.

### 8.2 Architectural Concepts

#### 8.2.1 Client-Server Architecture

- **Frontend**: Browser-based React SPA handling user interactions and UI rendering
- **Backend**: RESTful API server processing business logic and data operations
- **Separation of Concerns**: Clear boundaries between presentation, business logic, and data layers

#### 8.2.2 Spatial Data Handling

- **PostGIS Integration**: Extension of PostgreSQL for geographical and spatial operations
- **Coordinate Systems**: Use of standard geographical projections (e.g., WGS84)
- **Spatial Queries**: Efficient querying of railway elements within geographical bounds

#### 8.2.3 Real-time Communication

- **WebSocket Protocol**: For live updates during train simulations
- **Fallback Mechanisms**: Polling as alternative when WebSockets unavailable
- **Event-Driven Updates**: Push notifications for game state changes

#### 8.2.4 OSM Track Harvesting Policy

- **Railway Types**: Importer requests `rail`, `light_rail`, `subway`, `tram`, `narrow_gauge`, plus `construction` and `disused` variants to capture build-state metadata.
- **Service Filters**: `service` tags such as `yard`, `siding`, `spur`, `crossover`, `industrial`, or `military` are excluded to focus on mainline traffic.
- **Usage Filters**: Ways flagged with `usage=military` or `usage=tourism` are skipped; unspecified usage defaults to accepted.
- **Geometry Guardrails**: Segments shorter than 75 meters are discarded and track endpoints must snap to an existing station within 350 meters or the segment is ignored during loading.

### 8.3 User Interface Concepts

#### 8.3.1 Component-Based Architecture

- **React Components**: Modular, reusable UI elements
- **State Management**: Centralized state using Redux or Context API
- **Responsive Design**: Adaptive layouts for various screen sizes and devices

#### 8.3.2 Map Interaction

- **Leaflet Integration**: Interactive mapping library for geographical visualization
- **Layer Management**: Overlaying user railways on base OpenStreetMap tiles
- **Gesture Handling**: Mouse, keyboard, and touch interactions for map navigation and editing

#### 8.3.3 Game Interface Patterns

- **Toolbar**: Contextual tools for building and editing railway elements
- **Modal Dialogs**: For configuration, confirmation, and detailed information display
- **Dashboard**: Overview of user progress, resources, and network statistics

### 8.4 Security Concepts

#### 8.4.1 Authentication and Authorization

- **JWT Tokens**: Stateless authentication for API requests
- **OAuth Integration**: Support for third-party authentication providers
- **Role-Based Access**: Differentiated permissions for users and administrators

#### 8.4.2 Data Protection

- **Input Validation**: Sanitization of all user inputs to prevent injection attacks
- **HTTPS Encryption**: Secure communication between client and server
- **Data Privacy**: Compliance with privacy regulations for user data handling

### 8.5 Persistence Concepts

#### 8.5.1 Database Design

- **Schema Overview**: Core tables include `users`, `stations`, `tracks`, `trains`, and `train_schedules`, each backed by UUID primary keys and timestamp metadata for auditing.
- **Users**: Holds account metadata (`username`, `email`, `role`, hashed password) with JSON-ready preference storage and soft defaults for player roles.
- **Stations**: Stores OpenStreetMap references, station codes, and a `POINT` geometry (`SRID 4326`) to support spatial queries; a GiST index accelerates proximity searches.
- **Tracks**: Models line segments between stations using `LINESTRING` geometry plus operational attributes (length, speed limits, status, bidirectionality) and a uniqueness constraint on station pairs.
- **Trains & Schedules**: Captures rolling stock capabilities and their ordered stop plans (`sequence_index`, arrival/departure timestamps, dwell times) with cascading foreign keys for clean deletions.
- **Spatial Extensions**: Alembic migrations provision `postgis` and `pgcrypto` extensions; geometry columns use GeoAlchemy2 bindings for seamless ORM interactions.

#### 8.5.2 Data Access Patterns

- **ORM Layer**: SQLAlchemy 2.0 declarative models (see `backend/app/db/models.py`) expose typed entities that will feed repository and service layers.
- **Session Management**: A centralized engine/session factory (`backend/app/db/session.py`) pulls the database URL from environment-managed settings and keeps pooling under application control.
- **Environment Separation**: `.env` configuration exposes `DATABASE_URL`, `TEST_DATABASE_URL`, and `ALEMBIC_DATABASE_URL`, allowing the runtime, tests, and migration tooling to target different Postgres instances.
- **Schema Evolution**: Alembic configuration (`backend/alembic.ini`, `backend/migrations/`) provides repeatable migrations—the initial revision creates the PostGIS-enabled schema and GiST indexes.
- **Transaction Management**: Service-layer dependencies will acquire short-lived sessions (`SessionLocal`) ensuring explicit commit/rollback boundaries around game operations.

### 8.6 Development and Deployment Concepts

#### 8.6.1 Testing Strategy

- **Unit Testing**: Individual component and function testing
- **Integration Testing**: API endpoint and database interaction validation
- **End-to-End Testing**: Complete user workflow verification across browsers

#### 8.6.2 Deployment Pipeline

- **Containerization**: Docker for consistent environments
- **CI/CD**: Automated testing and deployment workflows
- **Static Hosting**: CDN-based delivery of frontend assets

#### 8.6.3 Performance Optimization

- **Lazy Loading**: On-demand loading of components and data
- **Caching Layers**: Redis for frequently accessed data
- **Asset Optimization**: Minification and compression of static resources