# bogos387/rrs architecture

> Architecture diagram of the GitHub repository bogos387/rrs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bogos387/rrs
- Repository: https://github.com/bogos387/rrs

## Overview

##### Project type and purpose
- This is a large C++/Qt–based desktop application: an open‐source Russian Railway Simulator (RRS).
- It includes a simulation engine (physics, pneumatics, electrical, coupling, train dynamics), a UI launcher, a 3D viewer, configuration editors/readers, offline conversion tools, logging, and deployment scripts.

##### File structure to extract architectural layers
- Top‐level subsystems:
- cfg, CfgReader, CfgEditor – configuration management (XML-based init data, device and train definitions)
- simulator/* – core simulation engine, subdivided into:
– device simulators (pneumatic, electro, brake, coupling, etc.)
– physics module
– ODE solvers (rk4, rkf5)
– model layer (data‐engine, server)
– modbus communication
– sound‐manager
– train abstraction
- simulator/udp-connection & sim-client – message‐passing between engine and viewer
- addons/* – type-specific locomotive modules (chs2t, ep20, tep70, vl60, passcar) plugged into core engine
- launcher & launcher2 – Qt Widgets and QML UIs to select routes, vehicles, simulation parameters
- viewer/* – 3D rendering subsystem (OpenSceneGraph), route loader, display engine, DMD plugin
- tools/* – offline data conversion (pathconv, profconv, routeconv)
- libJournal – unified logging API (file, syslog)
- filesystem – file‐system abstraction
- scripts & setup – deployment and installer configuration

##### Extract additional insights from the README
- RRS is configuration-driven (XML defines trains, devices, main resistance, routes).
- It claims full compatibility with ZDSimulator routes.

- Configuration Subsystem
- Simulation Engine
- Vehicle Addons
- Communication Layer (UDP / sim-client)
- Launcher UI (launcher, launcher2)
- Viewer (3D renderer, route loader, display)
- Tools (conversion utilities)
- Supporting Libraries (libJournal, filesystem)
- Deployment (scripts, installer)

- User → Launcher UI → writes init-data.xml (via Configuration Subsystem)
- Launcher UI → spawns Simulation Engine
- Simulation Engine loads XML configs → CfgReader → core modules → physics & solver → updates Model → logs via libJournal
- Simulation Engine → serializes simulation state → UDP → sim-client → Viewer
- Viewer → loads geometry & routes (cfg + viewer/route‐loader) → OpenSceneGraph display → user sees 3D scene
- Tools operate offline on same XML inputs → produce profiles, paths, route definitions

c. Architectural patterns and principles:
- Layered architecture: UI → Engine → Communication → Rendering
- Plugin-style modules: addons compiled into core engine offering extensibility per locomotive type
- Configuration-driven design: nearly all behavior driven by XML definitions + CfgReader/CfgEditor
- Message‐passing decoupling via UDP allows viewer and engine to run in separate processes/machines
- Separation of concerns: solver, physics, device simulation, data model, I/O, and UI each in its own module

d. Key technologies and frameworks:
- C++17, Qt Widgets & QML, QMake/CMake build system
- OpenSceneGraph for 3D rendering
- XML for configuration (parsed by CfgReader)
- Custom ODE solvers (RK4, RKF5) for physics integration
- UDP and Modbus for inter‐module communication
- libJournal for logging abstraction
- Inno Setup scripts for Windows installer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external

    %% UI Layer
    subgraph "Launcher UI" 
        Launcher["Launcher & Launcher2"]:::ui
    end

    %% Configuration Subsystem
    subgraph "Configuration Subsystem" 
        CFG["XML Configs (init-data.xml)"]:::file
        CfgReader["CfgReader"]:::config
        CfgEditor["CfgEditor"]:::config
    end

    %% Simulation Engine
    subgraph "Simulation Engine" 
        direction TB
        SimulatorCore["simulator/simulator"]:::sim
        subgraph "Device Simulators"
            DeviceSim["simulator/device"]:::sim
            Brakepipe["simulator/brakepipe"]:::sim
            Coupling["simulator/coupling & default-coupling"]:::sim
            CarBrakes["simulator/carbrakes-mech"]:::sim
        end
        Physics["simulator/physics"]:::sim
        subgraph "Solver"
            Solver["simulator/solver"]:::sim
            RK4["simulator/rk4"]:::sim
            RKF5["simulator/rkf5"]:::sim
        end
        Model["simulator/model"]:::sim
        Modbus["simulator/modbus"]:::sim
        Sound["simulator/sound-manager"]:::sim
        Train["simulator/train"]:::sim
        subgraph "Locomotive Plugins"
            CHS2T["addons/chs2t/chs2t"]:::plugin
            EP20["addons/ep20/ep20"]:::plugin
            TLep20["addons/ep20/blok-display"]:::plugin
            TEP70["addons/tep70/tep70"]:::plugin
            VL60Eq["addons/vl60/vl60-equipment"]:::plugin
            VL60K["addons/vl60/vl60k"]:::plugin
            VL60PK["addons/vl60/vl60pk"]:::plugin
            Passcar["addons/passcar/passcar"]:::plugin
        end
    end

    %% Communication Layer
    subgraph "Communication Layer"
        UDP["simulator/udp-connection"]:::comm
        SimClient["simulator/sim-client"]:::comm
    end

    %% Viewer Layer
    subgraph "Viewer" 
        direction TB
        OSG["viewer/viewer"]:::viewer
        Display["viewer/display"]:::viewer
        Library["viewer/library"]:::viewer
        RouteLoader["viewer/route-loader"]:::viewer
        DMD["viewer/osgdb_dmd"]:::viewer
        ZDS["viewer/zds-route-loader"]:::viewer
    end

    %% Offline Tools
    subgraph "Offline Tools"
        PathConv["tools/pathconv"]:::tools
        ProfConv["tools/profconv"]:::tools
        RouteConv["tools/routeconv"]:::tools
    end

    %% Supporting Libraries
    subgraph "Supporting Libraries"
        LibJournal["libJournal"]:::lib
        FileSystem["filesystem"]:::lib
    end

    %% Deployment
    subgraph "Deployment"
        Scripts["scripts"]:::deploy
        Setup["setup"]:::deploy
    end

    %% Relationships
    User -->|uses UI| Launcher
    Launcher -->|loads/writes XML| CFG
    CFG --> CfgReader
    CFG --> CfgEditor
    Launcher -->|spawns| SimulatorCore
    CfgReader -->|provides configs| SimulatorCore
    SimulatorCore --> DeviceSim
    SimulatorCore --> Physics
    SimulatorCore --> Solver
    Solver --> RK4
    Solver --> RKF5
    SimulatorCore --> Model
    SimulatorCore --> Modbus
    SimulatorCore --> Sound
    SimulatorCore --> Train
    SimulatorCore --> Brakepipe
    SimulatorCore --> Coupling
    SimulatorCore --> CarBrakes
    SimulatorCore --> CHS2T
    SimulatorCore --> EP20
    SimulatorCore --> TLep20
    SimulatorCore --> TEP70
    SimulatorCore --> VL60Eq
    SimulatorCore --> VL60K
    SimulatorCore --> VL60PK
    SimulatorCore --> Passcar
    SimulatorCore -->|serializes state| UDP
    UDP --> SimClient
    SimClient --> OSG
    OSG --> Display
    Display --> Library
    Display --> RouteLoader
    Display --> DMD
    Display --> ZDS
    SimulatorCore -->|logs via| LibJournal
    SimulatorCore -->|uses| FileSystem
    PathConv --> CFG
    ProfConv --> CFG
    RouteConv --> CFG
    Scripts --> SimulatorCore
    Scripts --> Viewer
    Setup --> Scripts

    %% Click Events
    click CFG "https://github.com/bogos387/rrs/tree/release/cfg/"
    click CfgReader "https://github.com/bogos387/rrs/tree/release/CfgReader/"
    click CfgEditor "https://github.com/bogos387/rrs/tree/release/CfgEditor/"
    click SimulatorCore "https://github.com/bogos387/rrs/tree/release/simulator/simulator/"
    click DeviceSim "https://github.com/bogos387/rrs/tree/release/simulator/device/"
    click Physics "https://github.com/bogos387/rrs/tree/release/simulator/physics/"
    click Solver "https://github.com/bogos387/rrs/tree/release/simulator/solver/"
    click RK4 "https://github.com/bogos387/rrs/tree/release/simulator/rk4/"
    click RKF5 "https://github.com/bogos387/rrs/tree/release/simulator/rkf5/"
    click Model "https://github.com/bogos387/rrs/tree/release/simulator/model/"
    click Modbus "https://github.com/bogos387/rrs/tree/release/simulator/modbus/"
    click Sound "https://github.com/bogos387/rrs/tree/release/simulator/sound-manager/"
    click Train "https://github.com/bogos387/rrs/tree/release/simulator/train/"
    click Brakepipe "https://github.com/bogos387/rrs/tree/release/simulator/brakepipe/"
    click Coupling "https://github.com/bogos387/rrs/tree/release/simulator/coupling/"
    click CarBrakes "https://github.com/bogos387/rrs/tree/release/simulator/carbrakes-mech/"
    click CHS2T "https://github.com/bogos387/rrs/tree/release/addons/chs2t/chs2t/"
    click EP20 "https://github.com/bogos387/rrs/tree/release/addons/ep20/ep20/"
    click TLep20 "https://github.com/bogos387/rrs/tree/release/addons/ep20/blok-display/"
    click TEP70 "https://github.com/bogos387/rrs/tree/release/addons/tep70/tep70/"
    click VL60Eq "https://github.com/bogos387/rrs/tree/release/addons/vl60/vl60-equipment/"
    click VL60K "https://github.com/bogos387/rrs/tree/release/addons/vl60/vl60k/"
    click VL60PK "https://github.com/bogos387/rrs/tree/release/addons/vl60/vl60pk/"
    click Passcar "https://github.com/bogos387/rrs/tree/release/addons/passcar/passcar/"
    click UDP "https://github.com/bogos387/rrs/tree/release/simulator/udp-connection/udp-connection/"
    click SimClient "https://github.com/bogos387/rrs/tree/release/simulator/sim-client/"
    click Launcher "https://github.com/bogos387/rrs/tree/release/launcher/"
    click OSG "https://github.com/bogos387/rrs/tree/release/viewer/viewer/"
    click Display "https://github.com/bogos387/rrs/tree/release/viewer/display/"
    click Library "https://github.com/bogos387/rrs/tree/release/viewer/library/"
    click RouteLoader "https://github.com/bogos387/rrs/tree/release/viewer/route-loader/"
    click DMD "https://github.com/bogos387/rrs/tree/release/viewer/osgdb_dmd/"
    click ZDS "https://github.com/bogos387/rrs/tree/release/viewer/zds-route-loader/"
    click PathConv "https://github.com/bogos387/rrs/tree/release/tools/pathconv/"
    click ProfConv "https://github.com/bogos387/rrs/tree/release/tools/profconv/"
    click RouteConv "https://github.com/bogos387/rrs/tree/release/tools/routeconv/"
    click LibJournal "https://github.com/bogos387/rrs/tree/release/libJournal/"
    click FileSystem "https://github.com/bogos387/rrs/tree/release/filesystem/"
    click Scripts "https://github.com/bogos387/rrs/tree/release/scripts/"
    click Setup "https://github.com/bogos387/rrs/tree/release/setup/"

    %% Styles
    classDef external fill:#ffffff,stroke:#000000;
    classDef ui fill:#c3d9ff,stroke:#0366d6;
    classDef file fill:#f0f0f0,stroke:#888888,stroke-dasharray: 2 2;
    classDef config fill:#d9f2d9,stroke:#2e8b57;
    classDef sim fill:#e0ffe0,stroke:#2e8b57;
    classDef plugin fill:#e6f7ff,stroke:#0066cc;
    classDef comm fill:#fff4e0,stroke:#d2691e;
    classDef viewer fill:#ffe4e1,stroke:#b22222;
    classDef tools fill:#f5f5f5,stroke:#808080;
    classDef lib fill:#f0f8ff,stroke:#4682b4;
    classDef deploy fill:#faf0e6,stroke:#a0522d;
```
