# navigraph/msfs-navigation-data-interface architecture

> Architecture diagram of the GitHub repository navigraph/msfs-navigation-data-interface, 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/navigraph/msfs-navigation-data-interface
- Repository: https://github.com/navigraph/msfs-navigation-data-interface

## Overview

##### Main Components
- WASM Module – (located in src/wasm): This component is built with Rust and handles downloading the navigation database file, interfacing via the commbus to communicate with the gauge, and providing the runtime functionality for the MSFS simulation. It includes modules such as the dispatcher, network helpers, download (with zip_handler), and JSON struct serializers.
- Database Layer – (located in src/database): A pure Rust implementation that manages interfacing with the DFD SQLite-based navigation data. This module encapsulates functions for executing SQL queries and handling data output (such as airport, airspace, airway, procedures, etc.).
- JavaScript Interface – (located in src/js): Provides a wrapper for invoking functionality from both the WASM module and potentially the Rust database. This component integrates with the CommBus API used by MSFS gauges, enabling JS code to trigger events (e.g., “NAVIGRAPH_CallFunction”) and listen for results.
- Examples & Demonstration Components – (examples/aircraft and examples/gauge): These sample implementations demonstrate how to integrate the interface components (both gauge UI elements and the aircraft panel integration) into an actual MSFS project.
- Build & Deployment Tools – (scripts, Cargo/TOML configuration files, Dockerfile, GitHub workflows): Although more on the operational side, these indicate how the project is built, tested, and integrated into CI/CD pipelines.

##### Relationships and Interactions
- The MSFS environment (or the aircraft panel) interacts with the WASM module (via the gauge configuration in Panel.cfg) using the CommBus event API.
- The WASM module communicates with the Rust Database layer by using the shared logic to process the DFD SQLite file. Although the database module is separate, it is conceptually “plugged into” the WASM module for handling SQL queries.
- The JavaScript interface layer acts as an alternative or complementary abstraction that exposes commands such as “GetAirport” or “ExecuteSQLQuery” – these calls eventually route through the CommBus to the WASM module.
- There’s a clear data flow from the initial request (either from JS or directly from the gauge in the sim) to the WASM module, which then may call into the database routines to retrieve or update navigation data.
- External deployment or update flows exist to download/build the WASM module (as mentioned in the README) and then include it in the aircraft’s panel folder.

##### Architectural Patterns and Design Principles
- Modularity: The project separates concerns by isolating the database handling, WASM functionalities, and the JavaScript API.
- Dual Interface Support: It supports interactions via both native WebAssembly and JavaScript, with the common communication channel (CommBus) used for exchanging messages.
- Layered Architecture: At the bottom is the core database layer; above, we have WASM and JS wrappers; on the top layer, the simulation environment (MSFS) integrates through panels and gauges.
- Event-Driven Communication: Emphasize the use of the CommBus for initiating function calls and receiving asynchronous responses.

##### Incorporate Relevant Technologies
- Rust/Cargo – for the core modules (database and WASM)
- WebAssembly (WASM) – for running performance-critical code within MSFS
- JavaScript and Node.js – wrapping and building the JS interface layer, along with tools like ESLint, TypeScript, and Rollup.
- SQLite (via DFD format) – as the underlying format for navigation data persistence.
- Docker, GitHub Actions CI/CD – (as indicated by Dockerfile, .github/workflows) tools for building and testing.
- CommBus API – the simulation-specific communication mechanism linking the gauge (whether JS or WASM) to the flight simulation environment.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "MSFS Simulation Environment"
        msfsSim("MSFS Simulation Environment"):::external
    end

    subgraph "JavaScript Interface (src/js)"
        jsInterface("JavaScript Interface"):::js
        js_index("index.ts"):::jsSub
        js_commbus("CommBus.d.ts"):::jsSub
        jsInterface --> js_index
        jsInterface --> js_commbus
    end

    subgraph "WASM Module (src/wasm)"
        wasmModule("WASM Module"):::rust
        wasm_lib("lib.rs"):::rustSub
        wasm_dispatcher("Dispatcher.rs"):::rustSub
        wasm_zip_handler("zip_handler.rs"):::rustSub
        wasmModule --> wasm_lib
        wasmModule --> wasm_dispatcher
        wasmModule --> wasm_zip_handler
    end

    subgraph "Database Layer (src/database)"
        dbLayer("Database Layer"):::rust
        db_main("database.rs"):::rustSub
        db_airport("airport.rs"):::rustSub
        dbLayer --> db_main
        dbLayer --> db_airport
    end

    subgraph "Examples & Demos"
        aircraft("Aircraft Integration"):::example
        gauge("Gauge Integration"):::example
    end

    subgraph "Build & Deployment Tools"
        buildScripts("Build Scripts"):::build
        ciTools("CI/CD & Build Config"):::build
    end

    %% External Interactions
    msfsSim -->|"NAVIGRAPH_CallFunction"| wasmModule
    wasmModule -->|"NAVIGRAPH_FunctionResult"| msfsSim
    jsInterface -->|"CommBus_API"| wasmModule
    wasmModule -->|"SQL_query_calls"| dbLayer

    %% Click Events
    click wasmModule "https://github.com/navigraph/msfs-navigation-data-interface/tree/v1/src/wasm"
    click wasm_lib "https://github.com/navigraph/msfs-navigation-data-interface/blob/v1/src/wasm/src/lib.rs"
    click wasm_dispatcher "https://github.com/navigraph/msfs-navigation-data-interface/blob/v1/src/wasm/src/dispatcher.rs"
    click wasm_zip_handler "https://github.com/navigraph/msfs-navigation-data-interface/blob/v1/src/wasm/src/download/zip_handler.rs"
    click dbLayer "https://github.com/navigraph/msfs-navigation-data-interface/tree/v1/src/database"
    click db_main "https://github.com/navigraph/msfs-navigation-data-interface/blob/v1/src/database/src/database.rs"
    click db_airport "https://github.com/navigraph/msfs-navigation-data-interface/blob/v1/src/database/src/output/airport.rs"
    click jsInterface "https://github.com/navigraph/msfs-navigation-data-interface/tree/v1/src/js"
    click js_index "https://github.com/navigraph/msfs-navigation-data-interface/blob/v1/src/js/index.ts"
    click js_commbus "https://github.com/navigraph/msfs-navigation-data-interface/blob/v1/src/js/CommBus.d.ts"
    click aircraft "https://github.com/navigraph/msfs-navigation-data-interface/tree/v1/examples/aircraft"
    click gauge "https://github.com/navigraph/msfs-navigation-data-interface/tree/v1/examples/gauge"
    click buildScripts "https://github.com/navigraph/msfs-navigation-data-interface/tree/v1/scripts"
    click ciTools "https://github.com/navigraph/msfs-navigation-data-interface/tree/v1/.github/workflows"

    %% Styles
    classDef external fill:#C3F587,stroke:#333,stroke-width:2px,color:#000;
    classDef js fill:#F9C0C0,stroke:#333,stroke-width:2px,color:#000;
    classDef rust fill:#AED6F1,stroke:#333,stroke-width:2px,color:#000;
    classDef example fill:#FDEBD0,stroke:#333,stroke-width:2px,color:#000;
    classDef build fill:#D5DBDB,stroke:#333,stroke-width:2px,color:#000;
    classDef rustSub fill:#D6EAF8,stroke:#333,stroke-width:1px,color:#000;
    classDef jsSub fill:#FADBD8,stroke:#333,stroke-width:1px,color:#000;
```
