# dotcorr/dcflight architecture

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

- Interactive diagram: https://gitdiagram.com/dotcorr/dcflight
- Repository: https://github.com/dotcorr/dcflight

## Overview

##### Project type and purpose
- This is a CLI-based toolkit called “DCFlight,” under development to simplify cross-platform app development.
- It consists of:
- A Dart CLI (`/cli`) that will orchestrate code generation, build commands, project scaffolding
- A “template/dcflight” example app demonstrating a custom UI framework
- A set of docs and landing pages for marketing

##### File structure
- Top level:
- `cli/`: the command-line interface, with its own `bin/`, `lib/`, `test/`, and `pubspec.yaml`
- `template/dcflight/`: example project that uses the framework, includes:
– `lib/framework`: core Dart UI framework (VDOM, state, native bridge)
– `ios/`, `android/`, `linux/`, `macos/`, `windows/`, `web/`: platform embedding layers
– `main.dart`: entry point wiring up Dart VM → framework → native
- `landing/`: marketing sites (React and static HTML)
- `docs/`: deep-dive design docs

##### README for additional insights
- The CLI is not yet functional, but the example app:
- Boots a Dart VM (via Flutter engine headlessly)
- Runs a VDOM-driven UI framework based on React + Flutter concepts
- Uses a native bridge package (`native_bridge/dispatcher.dart`) for CRUD ops on native views
- Employs a Yoga‐based layout engine, style manager, and component registry

##### Main components to feature
a. CLI component
– CLI process (Dart)
– Parses commands, scaffolds projects, orchestrates builds
b. Example App / Framework component
– Dart VM (launched by Flutter Engine headless)
– VDOM layer (reconciler, component tree)
– State and hooks module
– Native bridge dispatcher / handlers
– Yoga layout manager & style manager
c. Flutter Engine (headless)
– Provides Dart runtime
– No UI surface except when canvas is needed
d. Platform Embedding
– iOS / Android / macOS / Windows / Linux runner
– Platform channel / FFI entry points
– Receives CRUD calls and renders native UI views (buttons, text, scrollviews)
e. External libraries
– Yoga for flex layout
– Dart core libs
– Native platform SDKs (UIKit, Android Views, Win32, GTK, etc.)

##### Relationships and interactions
- CLI → (generates) → template project
- In example app:
1. Native runner launches Flutter engine (headless) → starts Dart VM
2. `main.dart` calls `initializeApplication()` → instantiates root component
3. VDOM reconciler diffing → calls native_bridge.dispatcher to create/update native widgets
4. Native handlers → call into platform SDK to render UI
5. Layout changes → YogaShadowTree → native layout calls
6. User events on native views → propagate via bridge back to Dart event handlers

##### Architectural patterns and design principles
- MVU/React style (unidirectional data flow, hooks, functional components)
- VDOM diff + reconciliation
- Adapter/Bridge pattern for native UI rendering
- Modularization: core framework decoupled from platform embedding
- Parallel flutter engine for Dart VM isolation

##### Detail focus
- Every layer from CLI invocation down to native view instantiation
- Module boundaries (e.g., `cli/lib` vs. `template/dcflight/lib/framework`)
- Communication channels (platform channels, FFI, timers, events)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        Pubspec["pubspec.yaml"]:::dart
        CLIBin["dc_maui.dart (bin)"]:::dart
        CLILib["dc_maui.dart (lib)"]:::dart
        CLITest["dc_maui_test.dart"]:::dart
    end

    %% Dart Layer
    subgraph "Dart Layer"
        direction TB
        Engine["Flutter Engine (headless)"]:::external
        DartVM["Dart VM"]:::external
        Main["main.dart"]:::dart
        Entry["entry.dart"]:::dart
        DebugTools["debug_tools.dart"]:::dart
        VDOM["vdom.dart"]:::dart
        Reconciler["reconciler.dart"]:::dart
        StateHook["state_hook.dart"]:::dart
        Dispatcher["dispatcher.dart"]:::dart
        DispatcherImp["dispatcher_imp.dart"]:::dart
        YogaEnums["yoga_enums.dart"]:::dart
        LayoutProps["layout_properties.dart"]:::dart
        StyleProps["style_properties.dart"]:::dart
    end

    %% Native Layer
    subgraph "Native Layer"
        direction TB

        subgraph "Platform Runners"
            direction TB
            iOSFlutter["iOS Flutter Dir"]:::native
            iOSProj["iOS Runner.xcodeproj"]:::native
            AndroidManifest["AndroidManifest.xml"]:::native
            AndroidMain["MainActivity.kt"]:::native
            LinuxFlutter["Linux Flutter Dir"]:::native
            LinuxMain["main.cc"]:::native
            MacFlutter["macOS Flutter Dir"]:::native
            MacInfo["Info.plist"]:::native
            WinFlutter["Windows Flutter Dir"]:::native
            WinMain["main.cpp"]:::native
            WebIndex["index.html"]:::native
            WebManifest["manifest.json"]:::native
        end

        subgraph "iOS Native Renderer"
            direction TB
            LayoutManager["DCMauiLayoutManager.swift"]:::native
            YogaTree["YogaShadowTree.swift"]:::native
            StyleManager["DCMauiStyleManager.swift"]:::native
            ButtonComp["DCMauiButtonComponent.swift"]:::native
            BridgeChannel["DCMauiBridgeChannel.swift"]:::native
            EventHandler["DCMauiEventMethodHandler.swift"]:::native
        end

        subgraph "Documentation & Marketing"
            direction TB
            DocModular["FLIGHT_FRAMEWORK_MODULARIZATION.md"]:::external
            DocEvents["events_flow.txt"]:::external
            LandingApp["App.js"]:::external
            LandingIndex["index.html"]:::external
        end
    end

    %% Connections
    Pubspec -->|reads| CLIBin
    CLIBin -->|orchestrates| CLILib
    CLILib --> CLITest
    CLILib -->|generates| Main

    iOSProj -->|includes| iOSFlutter
    AndroidMain -->|in| AndroidManifest
    LinuxMain -->|in| LinuxFlutter
    MacInfo -->|in| MacFlutter
    WinMain -->|in| WinFlutter
    WebManifest -->|configures| WebIndex

    Main -->|calls initialize| Entry
    Entry --> Reconciler
    Entry --> StateHook
    Reconciler --> Dispatcher
    StateHook --> Dispatcher
    Dispatcher --> DispatcherImp
    DispatcherImp -->|uses| BridgeChannel
    BridgeChannel --> EventHandler
    Reconciler --> YogaTree
    YogaTree --> LayoutManager
    StyleManager -->|applies| StyleProps
    YogaEnums --> LayoutProps
    LayoutProps -->|used by| LayoutManager

    Engine -->|hosts| DartVM
    DartVM --> Main

    DispatcherImp -->|FFI| iOSProj
    DispatcherImp -->|FFI| AndroidMain
    DispatcherImp -->|FFI| LinuxMain
    DispatcherImp -->|FFI| MacInfo
    DispatcherImp -->|FFI| WinMain
    DispatcherImp -->|JS| WebIndex

    %% Styles
    classDef dart fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef native fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px

    %% Click Events
    click Pubspec "https://github.com/dotcorr/dcflight/blob/main/cli/pubspec.yaml"
    click CLIBin "https://github.com/dotcorr/dcflight/blob/main/cli/bin/dc_maui.dart"
    click CLILib "https://github.com/dotcorr/dcflight/blob/main/cli/lib/dc_maui.dart"
    click CLITest "https://github.com/dotcorr/dcflight/blob/main/cli/test/dc_maui_test.dart"
    click Main "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/main.dart"
    click Reconciler "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/packages/vdom/reconciler.dart"
    click VDOM "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/packages/vdom/vdom.dart"
    click StateHook "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/packages/vdom/component/state_hook.dart"
    click Entry "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/utilities/entry.dart"
    click DebugTools "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/utilities/debug_tools.dart"
    click Dispatcher "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/packages/native_bridge/dispatcher.dart"
    click DispatcherImp "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/packages/native_bridge/dispatcher_imp.dart"
    click YogaEnums "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/constants/yoga_enums.dart"
    click LayoutProps "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/constants/layout_properties.dart"
    click StyleProps "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/lib/framework/constants/style_properties.dart"
    click iOSFlutter "https://github.com/dotcorr/dcflight/tree/main/template/dcflight/ios/Flutter/"
    click iOSProj "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/ios/Runner.xcodeproj"
    click AndroidManifest "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/android/app/src/main/AndroidManifest.xml"
    click AndroidMain "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/android/app/src/main/kotlin/com/example/dc_test/MainActivity.kt"
    click LinuxFlutter "https://github.com/dotcorr/dcflight/tree/main/template/dcflight/linux/flutter/"
    click LinuxMain "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/linux/runner/main.cc"
    click MacFlutter "https://github.com/dotcorr/dcflight/tree/main/template/dcflight/macos/Flutter/"
    click MacInfo "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/macos/Runner/Info.plist"
    click WinFlutter "https://github.com/dotcorr/dcflight/tree/main/template/dcflight/windows/flutter/"
    click WinMain "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/windows/runner/main.cpp"
    click WebIndex "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/web/index.html"
    click WebManifest "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/web/manifest.json"
    click LayoutManager "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/ios/Runner/DCMAUI/Coordination/Renderer/Layout/DCMauiLayoutManager.swift"
    click YogaTree "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/ios/Runner/DCMAUI/Coordination/Renderer/Layout/YogaShadowTree.swift"
    click StyleManager "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/ios/Runner/DCMAUI/Coordination/Renderer/style/DCMauiStyleManager.swift"
    click ButtonComp "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/ios/Runner/DCMAUI/Coordination/Components/DCMauiButtonComponent.swift"
    click BridgeChannel "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/ios/Runner/DCMAUI/channel/DCMauiBridgeChannel.swift"
    click EventHandler "https://github.com/dotcorr/dcflight/blob/main/template/dcflight/ios/Runner/DCMAUI/channel/events/DCMauiEventMethodHandler.swift"
    click DocModular "https://github.com/dotcorr/dcflight/blob/main/docs/FLIGHT_FRAMEWORK_MODULARIZATION.md"
    click DocEvents "https://github.com/dotcorr/dcflight/blob/main/docs/events_flow.txt"
    click LandingApp "https://github.com/dotcorr/dcflight/blob/main/landing/default/src/App.js"
    click LandingIndex "https://github.com/dotcorr/dcflight/blob/main/landing/default/public/index.html"
```
