# nus/dart_mavlink architecture

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

- Interactive diagram: https://gitdiagram.com/nus/dart_mavlink
- Repository: https://github.com/nus/dart_mavlink

## Overview

##### Project type and purpose
- This is an open-source Dart package (dart_mavlink) whose sole purpose is to parse and serialize MAVLink v1/v2 packets.
- It combines a code-generation step (to produce Dart bindings for MAVLink dialect XML definitions) and a runtime library (to do parsing, framing, CRC, and serialization).

##### Main components
A. MAVLink Dialect Definitions (Data Layer)
- Directory: mavlink/
- Contains XML files (e.g., common.xml, ardupilotmega.xml) that define messages, enums, and fields for each dialect.

B. Code Generator (Build/Tool Layer)
- File: tool/generate.dart
- Reads all XML dialect definitions under mavlink/
- Generates Dart source files under lib/dialects/ and updates lib/mavlink_dialect.dart

C. Generated Dart Dialect Modules (Source Layer)
- Directory: lib/dialects/
- For each dialect, a Dart file containing message classes and metadata

D. Core Runtime Library (API Layer)
- lib/crc.dart – cyclic redundancy check functions
- lib/mavlink_frame.dart – MAVLink packet framing/parsing logic
- lib/mavlink_parser.dart – state-machine parser for incoming byte streams
- lib/mavlink_message.dart – generic message wrapper and base class
- lib/mavlink_serialization (.serialize…) – converting messages to byte arrays
- lib/types.dart – common type definitions
- lib/mavlink_version.dart – version constants

E. Consumers
- example/ (example/parameter.dart, example/parser.dart) – demonstration code showing how to use the library
- test/ – suite of automated tests (unit and integration) that validate parsing and serialization

F. CI/CD and Configuration
- .github/workflows/dart.yml – GitHub Action to run tests on each push/pull request
- pubspec.yaml – package metadata and dependencies
- analysis_options.yaml – linting rules

##### Relationships and data flow
- The Code Generator reads the MAVLink XML files → emits Dart code under lib/dialects/
- The Core Runtime Library references the generated dialect modules to lookup message definitions at runtime
- The example code and the test suite both import the Core Runtime Library (and transitively the generated dialects) to parse or serialize messages
- CI/CD invokes test scripts which ensure correctness of parsing/serialization

##### Architectural patterns and design principles
- Clear separation of concerns:
- Data (XML dialects) vs. Code generation vs. Runtime library vs. Consumers
- Code-generation pipeline: XML → Dart source → compiled library
- Single crate/package: no microservices, but layered architecture

- Clear component names (use directory/file names as labels)
- Annotations for key technologies (Dart, XML) and processes (code generation, parsing, serialization)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Layer
    subgraph "Data Layer"
        DataXML["mavlink/"] 
    end

    %% Build/Tool Layer
    subgraph "Build/Tool Layer"
        CodeGen["tool/generate.dart"]
    end

    %% Generated Dart Dialect Modules
    subgraph "Generated Dart Dialect Modules"
        Generated["lib/dialects/"]
    end

    %% Core Runtime Library (API Layer)
    subgraph "Core Runtime Library"
        CRC["lib/crc.dart"]
        Frame["lib/mavlink_frame.dart"]
        ParserSM["lib/mavlink_parser.dart"]
        Message["lib/mavlink_message.dart"]
        Serialization["lib/mavlink.dart"]
        DialectRegistry["lib/mavlink_dialect.dart"]
        Types["lib/types.dart"]
        Version["lib/mavlink_version.dart"]
    end

    %% Consumers
    subgraph "Consumers"
        Example["example/parameter.dart\nexample/parser.dart"]
        Tests["test/"]
    end

    %% CI/CD & Config
    subgraph "CI/CD & Configuration"
        CI[".github/workflows/dart.yml"]
        Pubspec["pubspec.yaml"]
        Analysis["analysis_options.yaml"]
    end

    %% Relationships
    DataXML -->|"reads XML dialects"| CodeGen
    CodeGen -->|"generates Dart modules"| Generated
    CRC -->|"depends on message defs"| Generated
    Frame -->|"depends on message defs"| Generated
    ParserSM -->|"depends on message defs"| Generated
    Message -->|"depends on message defs"| Generated
    Serialization -->|"depends on message defs"| Generated
    DialectRegistry -->|"registers dialects"| Generated
    Types -->|"used by runtime"| Generated
    Version -->|"version info for runtime"| Generated
    Example -->|"imports Core Runtime"| CRC
    Example -->|"imports Core Runtime"| Frame
    Example -->|"imports Core Runtime"| ParserSM
    Example -->|"imports Core Runtime"| Message
    Example -->|"imports Core Runtime"| Serialization
    Example -->|"imports Core Runtime"| DialectRegistry
    Example -->|"imports Core Runtime"| Types
    Example -->|"imports Core Runtime"| Version
    Tests -->|"imports Core Runtime"| CRC
    Tests -->|"imports Core Runtime"| Frame
    Tests -->|"imports Core Runtime"| ParserSM
    Tests -->|"imports Core Runtime"| Message
    Tests -->|"imports Core Runtime"| Serialization
    Tests -->|"imports Core Runtime"| DialectRegistry
    Tests -->|"imports Core Runtime"| Types
    Tests -->|"imports Core Runtime"| Version
    CI -->|"runs tests on"| Tests

    %% Click Events
    click DataXML "https://github.com/nus/dart_mavlink/tree/main/mavlink/"
    click CodeGen "https://github.com/nus/dart_mavlink/blob/main/tool/generate.dart"
    click Generated "https://github.com/nus/dart_mavlink/tree/main/lib/dialects/"
    click CRC "https://github.com/nus/dart_mavlink/blob/main/lib/crc.dart"
    click Frame "https://github.com/nus/dart_mavlink/blob/main/lib/mavlink_frame.dart"
    click ParserSM "https://github.com/nus/dart_mavlink/blob/main/lib/mavlink_parser.dart"
    click Message "https://github.com/nus/dart_mavlink/blob/main/lib/mavlink_message.dart"
    click Serialization "https://github.com/nus/dart_mavlink/blob/main/lib/mavlink.dart"
    click DialectRegistry "https://github.com/nus/dart_mavlink/blob/main/lib/mavlink_dialect.dart"
    click Types "https://github.com/nus/dart_mavlink/blob/main/lib/types.dart"
    click Version "https://github.com/nus/dart_mavlink/blob/main/lib/mavlink_version.dart"
    click Example "https://github.com/nus/dart_mavlink/blob/main/example/parameter.dart"
    click Tests "https://github.com/nus/dart_mavlink/tree/main/test/"
    click CI "https://github.com/nus/dart_mavlink/blob/main/.github/workflows/dart.yml"
    click Pubspec "https://github.com/nus/dart_mavlink/blob/main/pubspec.yaml"
    click Analysis "https://github.com/nus/dart_mavlink/blob/main/analysis_options.yaml"

    %% Styles
    classDef data fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef tool fill:#ffcc99,stroke:#333,stroke-width:1px;
    classDef source fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef api fill:#99ccff,stroke:#333,stroke-width:1px;
    classDef consumers fill:#dddddd,stroke:#333,stroke-width:1px;
    classDef config fill:#e0b3ff,stroke:#333,stroke-width:1px;

    class DataXML data;
    class CodeGen tool;
    class Generated source;
    class CRC,Frame,ParserSM,Message,Serialization,DialectRegistry,Types,Version api;
    class Example,Tests consumers;
    class CI,Pubspec,Analysis config
```
