Overall Architecture and Class Diagrams
The current project architecture (Release 3) follows a blend between Clean architecture and Domain-Driven design.
The package diagram follows the current codebase and provides a high-level overview of the current packages and classes. Note that the folder-like tabs represent actual sub-folders containing a set of classes and the plug-in style items are standalone classes/files:
Below is a set of class diagrams and models generated by each of the sub-teams to explain how the current system interacts across frontend, backend, and simulation layers. Some diagrams are preserved from earlier releases for historical context; Release 3-specific notes are called out where relevant.
- Flow of State in
simulation-provider:
- Flow of Authentication:
From #106
- Component Nesting Hierarchy:
From #40
- Optimized Selection within Map Provider
From #106
- Ensuring State is Accurate
From #106
- Back-end Layered Architecture:
This diagram illustrates all the core folders contained within the /back directory of the velosim project with arrows depicting the logic and operations on how the folder interact with each other. A legend is provided in the bottom right hand corner to provide better visual clarity.
- API Structure:
This diagram depicts the Release 3 API structure. The /api/v1 surface now includes simulation, users, scenarios, logs, and traffic-template routers, while metrics and simulation WebSocket streaming are mounted separately in main.py for operational and authentication reasons. Each backend resource is contained within its own box with relevant HTTP methods listed for quick reference.
- ER Diagram
This ERD shows how the backend entities and relationships are structured in Release 3, including frame persistence and traffic-template data. Each entity is listed with its attributes and datatypes to support CRUD design and impact analysis.
Release 3 Note: The simulation model uses separate Driver and Vehicle entities (rather than the legacy single Resource abstraction), with traffic-aware routing and richer route/task lifecycle behavior. Diagrams in this section should be interpreted as Release 3 unless explicitly marked as historical.
- Simulator Conceptual Domain Model
- Communication Diagram For a Standard Simulation Loop
- Class Diagram of Simulation Entities:
- Driver Behaviour State Machine
The Release 3 Traffic State Machine complements the simulation entity and route architecture by governing how traffic events are loaded, activated, and applied during runtime. In practice, this state flow feeds the simulation's routing behavior and frame emission pipeline, which is why it should be read together with the simulation entity/class diagrams above.