164 lines
6.6 KiB
Markdown
164 lines
6.6 KiB
Markdown
# 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
|
|
- 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.
|