# viva-safeland/viva_safeland architecture

> Architecture diagram of the GitHub repository viva-safeland/viva_safeland, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/viva-safeland/viva_safeland
- Repository: https://github.com/viva-safeland/viva_safeland

## Overview

1. **Overall shape**
   ViVa-SAFELAND is primarily a **Python desktop simulation package** for safe landing validation. The core runtime lives in the `viva` package, while `docs/`, `tests/`, and `.github/workflows/` support documentation, verification, and release automation.

2. **Primary entry points**
   The application startup path appears to run through `viva/main.py` and `viva/launcher.py`, which likely coordinate initialization, UI startup, and scenario selection. `viva/__init__.py` makes the package importable, and `viva/viva_pegasus.py` suggests an alternate integration entrypoint or platform-specific variant.

3. **Runtime configuration boundary**
   `viva/env.py` is the central place for environment or configuration setup. In an architecture diagram, treat this as the boundary where runtime parameters, file paths, and execution settings are established before the rest of the app is launched.

4. **User interface subsystem**
   `viva/gui.py` and the `viva/GUI/` directory implement the desktop UI layer. The presence of `forest-dark` and `forest-light` themes indicates a themed Tk-style GUI rather than a web frontend. This layer is the operator-facing control surface for launching and controlling simulations.

5. **Simulation and rendering subsystem**
   The core simulation logic is organized under `viva/modules/`:
   - `simulator.py` for the simulation loop/state management
   - `render_drone.py` for visual rendering of the aerial vehicle
   - `motion_blur.py` for image-effect augmentation
   - `hmi.py` for human-machine interaction or command handling  
   These modules represent the heart of the visual validation pipeline.

6. **Data flow inside the app**
   The likely flow is: **user input in the GUI → launcher/main orchestration → environment setup → simulator loop → rendering / image effects → feedback back to the UI**. `hmi.py` is the control bridge between operator intent and simulation commands, while `render_drone.py` and `motion_blur.py` shape the generated visual output.

7. **External simulation / autopilot integration**
   The `gazebo/` and `pegasus/` directories indicate integration with **PX4/MAVLink-based simulation stacks**. Files like `pymavlink_px4_interface.py`, `viva_sitl.py`, and `pegasus_viva.py` suggest adapters for connecting the ViVa simulation flow to external flight-control or SITL environments. These are important architectural boundaries because they connect the visual simulation platform to vehicle/autopilot ecosystems.

8. **Scenario and backend variants**
   The duplicated interface files under both `gazebo/` and `pegasus/` imply multiple backend-specific adapters or experiment setups. If diagramming the system, model these as **integration layers** rather than core logic: the core app likely stays in `viva/`, while backend folders translate between ViVa and external simulators.

9. **Tests as architecture validation**
   `tests/test_01.py`, `test_02.py`, and `test_03.py` suggest a small but explicit test suite covering core behavior. These tests are the main verification boundary for the package and likely exercise package importability, simulation logic, or interface behavior.

10. **Documentation and publication pipeline**
   `docs/` and `mkdocs.yml` indicate MkDocs-based project documentation, with content split across installation, usage, API, and about pages. The GitHub Actions workflows in `.github/workflows/ci.yml` and `publish.yml` handle automated validation and package release/publishing.

11. **Packaging/tooling**
   `pyproject.toml`, `.python-version`, and `ruff.toml` show a modern Python packaging and linting setup. This is a standard library-level concern, but architecturally it matters because the project is distributed as a Python package and governed by code-quality automation.

12. **How to draw the boundaries**
   For an architecture diagram, the cleanest split is:
   - **Operator/UI layer:** `viva/gui.py`, `viva/GUI/`
   - **Core simulation engine:** `viva/modules/*`, `viva/simulator` logic
   - **Runtime orchestration/config:** `viva/main.py`, `viva/launcher.py`, `viva/env.py`
   - **External integration adapters:** `gazebo/`, `pegasus/`
   - **Support systems:** `tests/`, `docs/`, CI workflows  
   The main dependency direction is from UI/orchestration into the simulation modules, and from adapters outward to PX4/MAVLink/Gazebo-style external systems.

Main entry points: [`viva/modules/simulator.py`](https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/simulator.py) (Simulator), [`viva/launcher.py`](https://github.com/viva-safeland/viva_safeland/blob/main/viva/launcher.py) (Launcher), [`viva/gui.py`](https://github.com/viva-safeland/viva_safeland/blob/main/viva/gui.py) (GUI), [`tests/test_01.py`](https://github.com/viva-safeland/viva_safeland/blob/main/tests/test_01.py) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("Main<br/>entrypoint<br/>[main.py]"))
  node_launcher["Launcher<br/>orchestration<br/>[launcher.py]"]
  node_env["Env<br/>config boundary<br/>[env.py]"]
  node_gui["GUI<br/>desktop UI<br/>[gui.py]"]
  node_gui_assets["Themes<br/>ui assets<br/>[forest-dark.tcl]"]
  node_viva_pegasus(("Pegasus entry<br/>alt entrypoint<br/>[viva_pegasus.py]"))
end

subgraph group_core["Core simulation"]
  node_hmi["HMI<br/>control bridge<br/>[hmi.py]"]
  node_simulator[("Simulator<br/>simulation loop<br/>[simulator.py]")]
  node_render_drone["Render drone<br/>rendering<br/>[render_drone.py]"]
  node_motion_blur["Motion blur<br/>image effect<br/>[motion_blur.py]"]
end

subgraph group_integration["Integration"]
  node_gazebo_sitl["Gazebo SITL<br/>integration adapter<br/>[viva_sitl.py]"]
  node_gazebo_px4["Gazebo PX4<br/>mavlink bridge"]
  node_pegasus_viva["Pegasus bridge<br/>integration adapter<br/>[pegasus_viva.py]"]
  node_pegasus_px4["Pegasus PX4<br/>mavlink bridge"]
end

subgraph group_support["Support"]
  node_docs["Docs<br/>documentation<br/>[index.md]"]
  node_tests["Tests<br/>verification<br/>[test_01.py]"]
  node_ci["CI/CD<br/>automation<br/>[ci.yml]"]
end

node_main -->|"starts"| node_launcher
node_launcher -->|"configures"| node_env
node_launcher -->|"opens"| node_gui
node_gui -->|"themes"| node_gui_assets
node_gui -->|"commands"| node_hmi
node_hmi -->|"controls"| node_simulator
node_simulator -->|"renders"| node_render_drone
node_simulator -->|"augments"| node_motion_blur
node_main -->|"variant"| node_viva_pegasus
node_viva_pegasus -->|"adapts"| node_pegasus_viva
node_pegasus_viva -->|"bridges"| node_pegasus_px4
node_gazebo_sitl -->|"bridges"| node_gazebo_px4
node_launcher -->|"runs"| node_simulator
node_tests -.->|"verifies"| node_simulator
node_tests -.->|"verifies"| node_gui
node_ci -->|"runs"| node_tests
node_ci -->|"publishes"| node_docs

click node_main "https://github.com/viva-safeland/viva_safeland/blob/main/viva/main.py"
click node_launcher "https://github.com/viva-safeland/viva_safeland/blob/main/viva/launcher.py"
click node_env "https://github.com/viva-safeland/viva_safeland/blob/main/viva/env.py"
click node_gui "https://github.com/viva-safeland/viva_safeland/blob/main/viva/gui.py"
click node_gui_assets "https://github.com/viva-safeland/viva_safeland/blob/main/viva/GUI/forest-dark.tcl"
click node_hmi "https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/hmi.py"
click node_simulator "https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/simulator.py"
click node_render_drone "https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/render_drone.py"
click node_motion_blur "https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/motion_blur.py"
click node_viva_pegasus "https://github.com/viva-safeland/viva_safeland/blob/main/viva/viva_pegasus.py"
click node_gazebo_sitl "https://github.com/viva-safeland/viva_safeland/blob/main/gazebo/viva_sitl.py"
click node_gazebo_px4 "https://github.com/viva-safeland/viva_safeland/blob/main/gazebo/pymavlink_px4_interface.py"
click node_pegasus_viva "https://github.com/viva-safeland/viva_safeland/blob/main/pegasus/pegasus_viva.py"
click node_pegasus_px4 "https://github.com/viva-safeland/viva_safeland/blob/main/pegasus/pymavlink_px4_interface.py"
click node_docs "https://github.com/viva-safeland/viva_safeland/blob/main/docs/index.md"
click node_tests "https://github.com/viva-safeland/viva_safeland/blob/main/tests/test_01.py"
click node_ci "https://github.com/viva-safeland/viva_safeland/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_launcher,node_env,node_gui,node_gui_assets,node_viva_pegasus toneBlue
class node_hmi,node_simulator,node_render_drone,node_motion_blur toneAmber
class node_gazebo_sitl,node_gazebo_px4,node_pegasus_viva,node_pegasus_px4 toneMint
class node_docs,node_tests,node_ci toneRose
```

## Components

### Runtime

Application startup, environment setup, and operator-facing control flow.

- [Main](https://github.com/viva-safeland/viva_safeland/blob/main/viva/main.py): entrypoint · Primary application entrypoint. · `viva/main.py`
- [Launcher](https://github.com/viva-safeland/viva_safeland/blob/main/viva/launcher.py): orchestration · Starts and coordinates the desktop app. · `viva/launcher.py`
- [Env](https://github.com/viva-safeland/viva_safeland/blob/main/viva/env.py): config boundary · Central runtime and path configuration. · `viva/env.py`
- [GUI](https://github.com/viva-safeland/viva_safeland/blob/main/viva/gui.py): desktop UI · Operator-facing desktop interface. · `viva/gui.py`
- [Themes](https://github.com/viva-safeland/viva_safeland/blob/main/viva/GUI/forest-dark.tcl): ui assets · Tk-style theme assets for the GUI. · `viva/GUI/forest-dark.tcl`
- [Pegasus entry](https://github.com/viva-safeland/viva_safeland/blob/main/viva/viva_pegasus.py): alt entrypoint · Alternate integration entrypoint for Pegasus-oriented runs. · `viva/viva_pegasus.py`

### Core simulation

Simulation loop and visual validation modules.

- [HMI](https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/hmi.py): control bridge · Translates operator intent into simulation commands. · `viva/modules/hmi.py`
- [Simulator](https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/simulator.py): simulation loop · Core simulation state and execution loop. · `viva/modules/simulator.py`
- [Render drone](https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/render_drone.py): rendering · Renders the aerial vehicle for validation. · `viva/modules/render_drone.py`
- [Motion blur](https://github.com/viva-safeland/viva_safeland/blob/main/viva/modules/motion_blur.py): image effect · Applies visual blur augmentation to frames. · `viva/modules/motion_blur.py`

### Integration

Adapters for Gazebo, Pegasus, and PX4/MAVLink environments.

- [Gazebo SITL](https://github.com/viva-safeland/viva_safeland/blob/main/gazebo/viva_sitl.py): integration adapter · Connects ViVa to Gazebo-based simulation runs. · `gazebo/viva_sitl.py`
- [Gazebo PX4](https://github.com/viva-safeland/viva_safeland/blob/main/gazebo/pymavlink_px4_interface.py): mavlink bridge · PX4/MAVLink interface for Gazebo-side integration. · `gazebo/pymavlink_px4_interface.py`
- [Pegasus bridge](https://github.com/viva-safeland/viva_safeland/blob/main/pegasus/pegasus_viva.py): integration adapter · Adapter between Pegasus and ViVa flows. · `pegasus/pegasus_viva.py`
- [Pegasus PX4](https://github.com/viva-safeland/viva_safeland/blob/main/pegasus/pymavlink_px4_interface.py): mavlink bridge · PX4/MAVLink interface for Pegasus-side integration. · `pegasus/pymavlink_px4_interface.py`

### Support

Documentation, tests, and automation around the package.

- [Docs](https://github.com/viva-safeland/viva_safeland/blob/main/docs/index.md): documentation · MkDocs documentation site and content. · `docs/index.md`
- [Tests](https://github.com/viva-safeland/viva_safeland/blob/main/tests/test_01.py): verification · Small test suite covering core package behavior. · `tests/test_01.py`
- [CI/CD](https://github.com/viva-safeland/viva_safeland/blob/main/.github/workflows/ci.yml): automation · GitHub Actions workflows for validation and publishing. · `.github/workflows/ci.yml`

## Connections

- Main → Launcher: starts · Main delegates startup coordination to the launcher.
- Launcher → Env: configures · Launcher establishes runtime configuration before execution.
- Launcher → GUI: opens · Launcher initializes the desktop UI.
- GUI → Themes: themes · GUI loads themed UI assets.
- GUI → HMI: commands · Operator actions flow into the HMI bridge.
- HMI → Simulator: controls · HMI forwards control intent into the simulation loop.
- Simulator → Render drone: renders · Simulation produces vehicle visuals.
- Simulator → Motion blur: augments · Simulation frames are post-processed with blur effects.
- Main → Pegasus entry: variant · Secondary entrypoint for Pegasus-oriented execution.
- Pegasus entry → Pegasus bridge: adapts · Pegasus entrypoint hands off to the Pegasus adapter layer.
- Pegasus bridge → Pegasus PX4: bridges · Pegasus integration connects to PX4/MAVLink.
- Gazebo SITL → Gazebo PX4: bridges · Gazebo integration connects to PX4/MAVLink.
- Launcher → Simulator: runs · Launcher starts the simulation backend after setup.
- Tests → Simulator: verifies · Tests exercise core simulation behavior.
- Tests → GUI: verifies · Tests likely cover package and UI importability or behavior.
- CI/CD → Tests: runs · CI executes the test suite.
- CI/CD → Docs: publishes · Automation supports documentation and release workflows.