# aerosim-open/aerosim architecture

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

- Interactive diagram: https://gitdiagram.com/aerosim-open/aerosim
- Repository: https://github.com/aerosim-open/aerosim

## Overview

##### Primary components
- Core Simulation Engine: Represented by the Python package (aerosim) with its sub-modules such as core (simulation logic, configuration, simulation loop), io (input handlers, WebSockets servers), and visualization (camera, flight display, etc.).
- aerosim-controllers: Contains various flight control systems (e.g., autopilot, flight controller, primary flight display controller) and FMU build scripts.
- aerosim-core: Implements core simulation utilities, math operations, coordinate system conversions, and simulation actor definitions.
- aerosim-data: Manages data types, middleware interfaces (with examples for DDS, Kafka, ROS2), and FMU interface components.
- aerosim-dynamics-models: Contains aircraft dynamics, actuator models, and FMU build utilities for dynamics.
- aerosim-scenarios: Contains simulation scenarios, configurations, and translators to drive specific missions or test cases.
- aerosim-sensors: Provides sensor models (e.g., ADS-B, GNSS, IMU) and FMU build scripts for sensor emulation.
- aerosim-world & aerosim-world-link: Represent the simulation world, orchestration, and the interfacing layer between Rust and Python, including simulation management, logging, scene graph, and clock management.
- aerosim-macros: Likely contains Rust macros used by several other Rust crates.

- Renderers & Frontend:
- aerosim-app: A separate React/TypeScript application that serves as the visualization and control UI.
- aerosim-unreal-project and aerosim-omniverse-kit-app (as referenced in the README): Components for high-fidelity visualization using Unreal Engine and Omniverse.

##### Out relationships and data flows
- Data Flow & Communication:
- FMU interactions should also be explicitly represented; show how various FMU models (from controllers, dynamics, sensors) plug into the simulation—this can be depicted via connectors between FMU components and the main simulation module.

##### Architectural Patterns & Components
- At the bottom, group together the lower-level Rust crates (controllers, core, data, dynamics-models, sensors, scenarios, world, macros). They form the simulation “engine” foundations.
- At the top, include external and visualization components like the aerosim-app UI, Unreal Engine, and Omniverse interfaces.
- Design principles such as modularity (each Rust crate is independently developed yet integrated) and separation of concerns (distinct modules for simulation logic, data handling, UI integration, and FMU interfacing).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI & External Interfaces Layer
    subgraph "UI & External Interfaces"
        UI["Aerosim-App (React/TypeScript UI)"]:::ui
        Unreal["Aerosim Unreal Project (Renderer)"]:::ui
        Omniverse["Aerosim Omniverse Kit App (Renderer)"]:::ui
        Kafka["Kafka"]:::middleware
        DDS["DDS"]:::middleware
        ROS2["ROS2"]:::middleware
    end

    %% Python Orchestration Layer
    subgraph "Simulation Orchestration (Python)"
        PythonEngine["AeroSim Simulation Engine (Python)"]:::python
        CoreLogic["Core Logic"]:::python
        IOHandlers["IO Handlers"]:::python
        Visualization["Visualization Utilities"]:::python
    end

    %% Rust Components Layer
    subgraph "Simulation Engine Foundations (Rust)"
        RC["Aerosim Controllers (Rust FMU Models)"]:::rust
        RCore["Aerosim Core (Rust Simulation Utilities)"]:::rust
        RData["Aerosim Data (Rust Data Modeling & Middleware)"]:::rust
        RDynamics["Aerosim Dynamics Models (Rust Aircraft Dynamics)"]:::rust
        RScenarios["Aerosim Scenarios (Rust Simulation Scenarios)"]:::rust
        RSensors["Aerosim Sensors (Rust Sensor Models)"]:::rust
        RWorld["Aerosim World (Simulation World & Scene Graph)"]:::rust
        RWorldLink["Aerosim World-Link (Rust-Python Integration)"]:::rust
        RMacros["Aerosim Macros (Rust Macros)"]:::rust
    end

    %% Connections from Rust Components to Python Core Logic
    RC       -->|"fmu_integration"| CoreLogic
    RCore    -->|"sim_utils"| CoreLogic
    RData    -->|"data_model"| CoreLogic
    RDynamics-->|"dynamics"| CoreLogic
    RScenarios-->|"scenarios"| CoreLogic
    RSensors -->|"sensor_models"| CoreLogic
    RWorld   -->|"world_data"| CoreLogic
    RWorldLink-->|"integration"| CoreLogic
    RMacros  -->|"macros"| CoreLogic

    %% Connect Python Engine with its submodules
    PythonEngine --> CoreLogic
    PythonEngine --> IOHandlers
    PythonEngine --> Visualization

    %% WebSocket channel between IO Handlers and UI
    IOHandlers <-->|"websocket"| UI

    %% Visualization connections to Renderers
    Visualization -->|"render_data"| Unreal
    Visualization -->|"render_data"| Omniverse

    %% RData external middleware connections
    RData -->|"kafka"| Kafka
    RData -->|"dds"| DDS
    RData -->|"ros2"| ROS2

    %% Click Events for Python Components
    click PythonEngine "https://github.com/aerosim-open/aerosim/tree/main/aerosim/src/aerosim"
    click CoreLogic "https://github.com/aerosim-open/aerosim/tree/main/aerosim/src/aerosim/core"
    click IOHandlers "https://github.com/aerosim-open/aerosim/tree/main/aerosim/src/aerosim/io"
    click Visualization "https://github.com/aerosim-open/aerosim/tree/main/aerosim/src/aerosim/visualization"

    %% Click Events for Rust Components
    click RC "https://github.com/aerosim-open/aerosim/tree/main/aerosim-controllers"
    click RCore "https://github.com/aerosim-open/aerosim/tree/main/aerosim-core"
    click RData "https://github.com/aerosim-open/aerosim/tree/main/aerosim-data"
    click RDynamics "https://github.com/aerosim-open/aerosim/tree/main/aerosim-dynamics-models"
    click RScenarios "https://github.com/aerosim-open/aerosim/tree/main/aerosim-scenarios"
    click RSensors "https://github.com/aerosim-open/aerosim/tree/main/aerosim-sensors"
    click RWorld "https://github.com/aerosim-open/aerosim/tree/main/aerosim-world"
    click RWorldLink "https://github.com/aerosim-open/aerosim/tree/main/aerosim-world-link"
    click RMacros "https://github.com/aerosim-open/aerosim/tree/main/aerosim-macros"

    %% Class Definitions for Colours
    classDef python fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef rust fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef ui fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef middleware fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
