# dart-native/dart_native architecture

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

- Interactive diagram: https://gitdiagram.com/dart-native/dart_native
- Repository: https://github.com/dart-native/dart_native

## Overview

The DartNative project is essentially a bridge that enables direct communication between Flutter’s Dart code and native APIs (Android, iOS, and macOS) without relying on the traditional Flutter channel. The solution spans multiple submodules (e.g., dart_native and dart_native_gen) and is organized into distinct areas for Dart code, native code (Objective-C/Swift for iOS/macOS and Java/C++ for Android), and the code generation infrastructure.

##### Main Components
- Dart Application Layer:
- This contains the primary Dart code that developers write.
- It includes the dart_native package that provides functions such as synchronous and asynchronous method invocations, finalizer support, and automatic object marshalling.
- The dart_native_gen package is used for auto-generating bridging code based on annotations, and integrates with build_runner to generate native bindings.
- Native Bridge Layer:
- For Android: Consists of Java classes (as seen in dart_native/android and dart_native_gen/example/android) that register native methods and perform JNI calls. There is also low-level C/C++ code (in dart_native/android/src/main/jni) which handles callbacks and native invoker functionality.
- For iOS/macOS: Contains Objective-C and Swift code (in dart_native/ios, dart_native/macos) that sets up interfaces, implements method calls, manages memory (including finalizers), and handles bridging with Dart. There are xcframeworks, podspecs, and build scripts to support the integration.
- Code Generation & Build Infrastructure:
- The use of build_runner and the dart_native_gen package is critical. This layer automatically generates bridging code (with files like “<generated-name>.dn.dart”) that streamlines the interoperation between Dart and native languages.
- CI/CD & Project Management:
- There are GitHub workflows, metadata files, and configuration scripts (such as .fvm, pubspec.yaml) that set up continuous integration and dependency management.

##### Relationships & Interactions
- The Dart application layer directly calls the methods provided by the dart_native package. These calls are dynamically dispatched – both synchronously and asynchronously.
- Generated code (by dart_native_gen) provides wrappers that encapsulate the details of marshaling data between Dart and the native layer.
- On the native side, the corresponding interface classes in Java/Objective-C handle the method invocations. They further delegate the work by calling into lower-level C/C++ code (JNI on Android, and Objective-C bridging code on iOS/macOS).
- There is bidirectional communication:
- Native code can invoke Dart callbacks (e.g., via registered method call handlers and finalizer registration).
- Dart can initiate calls into native libraries by specifying the interface name and parameters.

##### Architectural Patterns & Design Principles
- Bridging Pattern: Instead of relying on the traditional Flutter channel, the project uses a direct function call paradigm with dynamic binding.
- Code Generation: Minimal boilerplate is achieved via automated code generation based on annotated classes and entry points.
- Native Interoperability: Direct cross-language method calls with automatic type conversions (marshalling) between Dart, Java, Objective-C, and associated C/C++ components.
- Separation of Concerns: Clear isolation is maintained between the Dart layer, native codebases (for each platform), and build/configuration tools.

##### Relevant Technologies, Frameworks, or Libraries
- Dart & Flutter ecosystem (build_runner, pubspec management).
- Native language ecosystems: Java for Android, Objective-C/Swift for iOS/macOS.
- C/C++ libraries (visible in the JNI folder for Android and similar native libraries for iOS).
- CI tools (GitHub Actions workflows, Travis CI).

##### Final Reminder
- Your objective is to map out all interactions between Dart, its generated code, and native layers – do not shy away from including as many components as possible for clarity.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Dart Layer"
        A["Dart Native Package"]:::dart
        B["Auto-Generated Bridging Code"]:::dart
    end

    subgraph "Android Native Bridge"
        C["Android Java Components"]:::android
        D["Android JNI/C++ Components"]:::android
    end

    subgraph "iOS/macOS Native Bridge"
        E["iOS Objective-C/Swift Components"]:::ios
        F["macOS Objective-C Components"]:::ios
    end

    subgraph "Build & Code Generation"
        G["Code Generation & Build Infrastructure"]:::build
    end

    H["CI/CD & Project Management"]:::ci

    %% Relationships
    A -->|"calls"| B
    G -->|"generates"| B
    B -->|"bridges_to"| C
    C -->|"delegates_to"| D
    B -->|"bridges_to"| E
    B -->|"bridges_to"| F
    D -.->|"callback"| A
    E -.->|"callback"| A
    F -.->|"callback"| A
    H -->|"triggers"| G

    %% Click Events
    click A "https://github.com/dart-native/dart_native/blob/master/dart_native/lib/dart_native.dart"
    click B "https://github.com/dart-native/dart_native/blob/master/dart_native_gen/lib/dart_native_gen.dart"
    click C "https://github.com/dart-native/dart_native/tree/master/dart_native/android/src/main/java/com/dartnative/dart_native/"
    click D "https://github.com/dart-native/dart_native/tree/master/dart_native/android/src/main/jni/src/"
    click E "https://github.com/dart-native/dart_native/tree/master/dart_native/ios/Classes/"
    click F "https://github.com/dart-native/dart_native/tree/master/dart_native/macos/Classes/"
    click G "https://github.com/dart-native/dart_native/blob/master/dart_native_gen/build.yaml"
    click H "https://github.com/dart-native/dart_native/tree/master/.github/workflows/"

    %% Styles
    classDef dart fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef android fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef ios fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef build fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef ci fill:#e6ccff,stroke:#333,stroke-width:2px;
```
