zwitschi/rail-game
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
rail-game/docs/architecture.md
zwitschi 68048ff574
Some checks failed
Backend CI / lint-and-test (push) Failing after 2m27s
Details
Frontend CI / lint-and-build (push) Successful in 57s
Details
feat: Add combined track functionality with repository and service layers 
- Introduced CombinedTrackModel, CombinedTrackCreate, and CombinedTrackRepository for managing combined tracks.
- Implemented logic to create combined tracks based on existing tracks between two stations.
- Added methods to check for existing combined tracks and retrieve constituent track IDs.
- Enhanced TrackModel and TrackRepository to support OSM ID and track updates.
- Created migration scripts for adding combined tracks table and OSM ID to tracks.
- Updated services and API endpoints to handle combined track operations.
- Added tests for combined track creation, repository methods, and API interactions.
2025-11-10 14:12:28 +01:00

6.7 KiB
Raw Permalink Blame History

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
  • Map visualization and interaction
  • Train scheduling and simulation
  • 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.

6. Runtime View

Runtime scenarios, sequence diagrams, and performance considerations are documented in 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.

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.