# betaflight/blackbox-log-viewer architecture

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

- Interactive diagram: https://gitdiagram.com/betaflight/blackbox-log-viewer
- Repository: https://github.com/betaflight/blackbox-log-viewer

## Overview

##### Main Components

a. User Interface (UI) Layer:
- Represented by the primary HTML file (index.html) and assets in the “public” folder (images, CSS, client-side JavaScript).
- The UI includes interactive elements (e.g., “Open log file/video” button, seek bar, graph displays, dialogs) that allow users to load, view, and interact with logs and videos.

b. Core Application Logic (Frontend Application Core):
- The “src” folder contains key modules such as log parsing (e.g., flightlog.js, flightlog_parser.js), graph configuration (graph_config.js and associated dialogs), and other tools (e.g., gps_transform.js, decoders.js).
- This layer encapsulates the business logic, including synchronizing logs with video playback, graphing, and video export functionalities.

c. Web Workers & Export Modules:
- The “webm-writer” subdirectory also indicates a clear module for exporting graphs as WebM video by handling video encoding.

d. External Libraries & Vendor Code:
- Files in “public/js” (e.g., FileSaver.js, three.js, jquery-related libraries) and the “src/vendor” directory represent 3rd-party libraries that assist with UI, data processing, animation, or other functionalities.
- These libraries are integrated into the core code base to enable specific features such as graphing and multimedia handling.

e. Development & Build Tools:
- Configuration files such as package.json, vite.config.js, and the presence of yarn scripts point to a modern development environment with Vite for bundling, hot module reloading, and other optimizations.
- Directories like “test” indicate that automated testing and sample configurations are part of the quality assurance process.

##### Relationships and Interactions
- The user launches the application through the browser (indexed by index.html), which loads assets from the “public” directory.
- UI actions drive the core application logic found in the “src” modules. For instance, when a log file is loaded, the parser module (flightlog_parser.js) processes the file and prepares data for the graph modules.
- Graphing components (graph_config, graph_spectrum, etc.) render visualizations, and any computationally heavy tasks (e.g., CSV, GPX exports) are offloaded to dedicated Web Workers which communicate back using postMessage mechanisms.
- External libraries (jQuery, FileSaver.js, three.js) interface directly with the UI components or assist in processing data, enabling a smooth interactive experience.
- Development tooling (Vite, Yarn, nvm) sits outside the runtime architecture but is critical for builds, testing, and deployment.

##### Architectural Patterns & Design Principles
- There is a clear separation of concerns: the presentation/UI layer (HTML/CSS, static assets) is decoupled from the application logic (src modules) and specialized worker processes.
- The PWA design pattern is in use, meaning the application is built to function both online and offline.
- Modularity is key: individual functionalities like log parsing, data visualization, and export functions are implemented as discrete modules, ensuring maintainability and ease of testing.

##### Additional Note
- Architecture’s modularity, PWA nature (offline capability), and the integration of third-party libraries that extend functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UI_index["index.html"]:::ui
        UI_css["public/css"]:::ui
        UI_images["public/images"]:::ui
        UI_js["public/js"]:::ui
    end

    %% Core Application Logic
    subgraph "Core Application Logic"
        CORE["src"]:::core
        %% Log Parsing Module
        subgraph "Log Parsing Module"
            FLP["src/flightlog_parser.js"]:::core
            FL["src/flightlog.js"]:::core
        end
        %% Graphing Module
        subgraph "Graphing Module"
            GC["src/graph_config.js"]:::core
            GCD["src/graph_config_dialog.js"]:::core
            GS["src/graph_spectrum.js"]:::core
            GSC["src/graph_spectrum_calc.js"]:::core
            GSP["src/graph_spectrum_plot.js"]:::core
            GR["src/grapher.js"]:::core
            GM["src/graph_map.js"]:::core
            GMMS["src/graph_minmax_setting_menu.js"]:::core
            GL["src/graph_legend.js"]:::core
        end
        %% Other Modules
        OTHER["Other Modules (craft_2d.js, craft_3d.js, gps_transform.js, tools.js)"]:::core
    end

    %% Web Workers & Export Modules
    subgraph "Web Workers & Export Modules"
        WORKERS["public/js/webworkers"]:::worker
        VIDEO["public/js/webm-writer"]:::worker
    end

    %% External Libraries & Vendor Code
    subgraph "External Libraries & Vendor Code"
        FS["public/js/FileSaver.js"]:::external
        THREE["public/js/three.js"]:::external
        JQUERY["public/js/jquery.ba-throttle-debounce.js"]:::external
        REAL["public/js/real.js"]:::external
        SEMVER["public/js/semver.js"]:::external
        VENDOR["src/vendor"]:::external
    end

    %% Development & Build Tools
    subgraph "Development & Build Tools"
        PKG["package.json"]:::dev
        VITE["vite.config.js"]:::dev
        TEST["test (directory)"]:::dev
    end

    %% Interactions / Data Flow
    UI_index -->|"LoadsAssets"| CORE
    UI_index -->|"UserActions"| CORE

    CORE -->|"ParsesLogFiles"| FLP
    CORE -->|"ParsesLogFiles"| FL
    CORE -->|"ProvidesGraphData"| GC
    CORE -->|"ProvidesGraphData"| GCD
    CORE -->|"ProvidesGraphData"| GS
    CORE -->|"ProvidesGraphData"| GSC
    CORE -->|"ProvidesGraphData"| GSP
    CORE -->|"ProvidesGraphData"| GR
    CORE -->|"ProvidesGraphData"| GM
    CORE -->|"ProvidesGraphData"| GMMS
    CORE -->|"ProvidesGraphData"| GL
    CORE -->|"CoordinatesModules"| OTHER

    CORE -->|"OffloadsTasks"| WORKERS
    CORE -->|"HandlesVideoExport"| VIDEO

    UI_index -->|"UtilizesAsset"| FS
    UI_js -->|"UtilizesAsset"| THREE
    UI_js -->|"UtilizesAsset"| JQUERY
    CORE -->|"UtilizesLibrary"| REAL
    CORE -->|"UtilizesLibrary"| SEMVER
    CORE -->|"UtilizesVendor"| VENDOR

    PKG -.->|"BuildConfig"| CORE
    VITE -.->|"BundlesAssets"| CORE
    TEST -.->|"TestsModules"| CORE

    %% Click Events
    click UI_index "https://github.com/betaflight/blackbox-log-viewer/blob/master/index.html"
    click UI_css "https://github.com/betaflight/blackbox-log-viewer/tree/master/public/css"
    click UI_images "https://github.com/betaflight/blackbox-log-viewer/tree/master/public/images"
    click UI_js "https://github.com/betaflight/blackbox-log-viewer/tree/master/public/js"

    click CORE "https://github.com/betaflight/blackbox-log-viewer/tree/master/src"

    click FLP "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/flightlog_parser.js"
    click FL "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/flightlog.js"

    click GC "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/graph_config.js"
    click GCD "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/graph_config_dialog.js"
    click GS "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/graph_spectrum.js"
    click GSC "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/graph_spectrum_calc.js"
    click GSP "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/graph_spectrum_plot.js"
    click GR "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/grapher.js"
    click GM "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/graph_map.js"
    click GMMS "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/graph_minmax_setting_menu.js"
    click GL "https://github.com/betaflight/blackbox-log-viewer/blob/master/src/graph_legend.js"

    click WORKERS "https://github.com/betaflight/blackbox-log-viewer/tree/master/public/js/webworkers"
    click VIDEO "https://github.com/betaflight/blackbox-log-viewer/tree/master/public/js/webm-writer"

    click FS "https://github.com/betaflight/blackbox-log-viewer/blob/master/public/js/FileSaver.js"
    click THREE "https://github.com/betaflight/blackbox-log-viewer/blob/master/public/js/three.js"
    click JQUERY "https://github.com/betaflight/blackbox-log-viewer/blob/master/public/js/jquery.ba-throttle-debounce.js"
    click REAL "https://github.com/betaflight/blackbox-log-viewer/blob/master/public/js/real.js"
    click SEMVER "https://github.com/betaflight/blackbox-log-viewer/blob/master/public/js/semver.js"
    click VENDOR "https://github.com/betaflight/blackbox-log-viewer/tree/master/src/vendor"

    click PKG "https://github.com/betaflight/blackbox-log-viewer/blob/master/package.json"
    click VITE "https://github.com/betaflight/blackbox-log-viewer/blob/master/vite.config.js"
    click TEST "https://github.com/betaflight/blackbox-log-viewer/tree/master/test"

    %% Styles
    classDef ui fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef core fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef worker fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef dev fill:#cce5ff,stroke:#004085,stroke-width:2px;
```
