# Rail Game Architecture Documentation

This document follows the arc42 template for software architecture documentation.

## 1. Introduction and Goals

### 1.1 Requirements Overview

The Rail Game is a browser-based railway simulation game that allows users to build and manage their own railway networks using real-world railway maps from OpenStreetMap. Key features include:

- Visualization of real-world railway maps
- Interactive building and management of railway networks
- Dynamic train scheduling and simulation
- User authentication and profiles
- Leaderboards and achievements
- Potential multiplayer elements

### 1.2 Quality Goals

- **Usability**: Intuitive interfaces for map interaction and network management
- **Performance**: Smooth real-time updates and responsive UI
- **Reliability**: Robust error handling and data integrity
- **Security**: Secure user authentication and data protection
- **Scalability**: Support for growing user base and complex networks

### 1.3 Stakeholders

- **Users**: Players who build and manage railway networks
- **Developers**: Team maintaining and extending the application
- **Administrators**: Managing user accounts and system operations

## 2. Constraints

### 2.1 Technical Constraints

- **Browser Compatibility**: Must work on modern web browsers supporting HTML5, CSS3, and JavaScript
- **Backend Language**: Python-based using FastAPI or Flask frameworks
- **Database**: PostgreSQL with PostGIS for spatial data handling
- **Mapping**: Integration with Leaflet and OpenStreetMap data

### 2.2 Organizational Constraints

- Open-source project hosted on GitHub
- Follows standard web development practices and security guidelines

### 2.3 Conventions

- Use Git for version control with conventional commit messages
- Follow React best practices for frontend development
- Implement RESTful API design for backend services

## 3. Context and Scope

### 3.1 Business Context

The Rail Game provides an educational and entertaining simulation of railway network management. It leverages real-world geographical data to create an immersive experience for users interested in transportation systems and strategy games.

### 3.2 Technical Context

The system interacts with:

- **OpenStreetMap**: Source of real-world map and railway data
- **Web Browsers**: Primary interface for users
- **PostgreSQL/PostGIS**: Storage and spatial queries for railway data
- **External APIs**: Potential integrations for additional features (e.g., weather, real-time data)

### 3.3 System Scope

**In Scope:**

- User registration and authentication
- Railway network building and management
- Train scheduling and simulation
- Map visualization and interaction
- Leaderboards and user profiles

**Out of Scope:**

- Real-world train control systems
- Physical railway operations
- Multiplayer real-time collaboration (initial version)

## 4. Solution Strategy

### 4.1 Technology Choices

- **Frontend**: React-based single-page application for responsive UI
- **Backend**: Python FastAPI/Flask for RESTful APIs and real-time features
- **Database**: PostgreSQL with PostGIS for efficient spatial data handling
- **Mapping**: Leaflet library for interactive maps integrated with OpenStreetMap

### 4.2 Architectural Patterns

- **Client-Server Architecture**: Separation of frontend and backend concerns
- **RESTful API**: For communication between frontend and backend
- **Component-Based UI**: Using React for modular frontend development
- **ORM**: SQLAlchemy for database abstraction

### 4.3 Key Decisions

- 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

The detailed building block view now lives in [05_Building_Block_View.md](./05_Building_Block_View.md).

## 6. Runtime View

Runtime scenarios, sequence diagrams, and performance considerations are documented in [06_Runtime_View.md](./06_Runtime_View.md).

## 7. Deployment View

### 7.1 Infrastructure Overview

- **Application Containers**: Backend (FastAPI + Uvicorn) and frontend (Vite/Node) each ship with dedicated Dockerfiles under `backend/` and `frontend/`.
- **Data Services**: PostgreSQL with PostGIS and Redis run as managed containers; volumes persist database state between restarts.
- **Reverse Proxy**: An Nginx gateway routes `/api` traffic to the backend service and serves built frontend assets in production deployments.

### 7.2 Local Development Topology

- `docker-compose.yml` orchestrates backend, frontend, Postgres/PostGIS, Redis, and Nginx for an end-to-end sandbox.
- Developers may alternatively run the frontend and backend directly via `npm run dev` and `uvicorn` while relying on the compose-managed data services.
- Environment variables are loaded from the repository root `.env` file (not tracked); a sample configuration lives at `.env.example`.

### 7.3 Continuous Integration & Delivery

- **CI Pipelines**: GitHub Actions lint and format both stacks, execute `pytest`, and run Playwright login flows on every pull request.
- **Build Artifacts**: Successful pipelines publish container images tagged with the commit SHA to the project registry (planned).
- **Promotion Strategy**: Main branch builds deploy to a shared staging environment; tagged releases promote to production once smoke tests pass (planned).

### 7.4 Environment Configuration

- **Secrets Management**: Local development uses `.env` files; higher environments will source secrets from the cloud provider's vault service (e.g., AWS Secrets Manager) with runtime injection.
- **Database Migration**: Alembic migrations execute during deployment rollout to guarantee schema alignment before application start.
- **Feature Flags**: Environment-specific toggles (planned) will allow gradual rollout of simulation and multiplayer features.

### 7.5 Observability and Operations

- **Logging**: Structured JSON logs emitted from FastAPI are shipped to centralized storage (e.g., OpenSearch) via Fluent Bit sidecars (planned).
- **Metrics**: Prometheus exporters for application and database metrics inform Grafana dashboards tracking request rate, latency, and simulation throughput.
- **Alerting**: PagerDuty escalation policies will trigger on error budgets and availability SLO breaches once production traffic begins.

## 8. Concepts

Concept catalogs and supporting models are maintained in [08_Concepts.md](./08_Concepts.md).

## 9. Design Decisions

To be detailed in subsequent sections.

## 10. Quality Requirements

To be detailed in subsequent sections.

## 11. Risks and Technical Debt

To be detailed in subsequent sections.

## 12. Glossary

To be detailed in subsequent sections.