# whyself/ai_native_editor architecture

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

- Interactive diagram: https://gitdiagram.com/whyself/ai_native_editor
- Repository: https://github.com/whyself/ai_native_editor

## Overview

1. **Overall shape**
   - This is a Flutter cross-platform desktop/mobile app called `ai_native_editor`.
   - The repository is organized as a single Flutter application plus two vendored Flutter packages under `packages/`: `flutter_math_fork` and `flutter_tex`.
   - The app itself appears to be an AI-assisted editor with a multi-pane workspace, file browser, live content model, and a chat/AI side panel.

2. **Top-level app composition**
   - `lib/main.dart` and `lib/app.dart` are the entry points into the Flutter UI.
   - The main shell is built from `lib/widgets/layout/app_shell.dart`, which likely composes the major regions: file panel, editor area, AI panel, and settings surfaces.
   - The app is intended to run on Android, iOS, Linux, macOS, Windows, and web, as reflected by the platform folders.

3. **Primary UI boundaries**
   - `lib/widgets/file_panel/` is the workspace/file navigation boundary.
   - `lib/widgets/editor/` is the central editing boundary, including pane trees, split nodes, markdown editing/preview, PDF viewing, toolbars, drag/drop overlays, and pane title bars.
   - `lib/widgets/ai_panel/` is the conversational/assistant boundary.
   - `lib/widgets/settings/` contains the settings sheet, likely opened as a modal or side sheet.
   - `lib/widgets/layout/` contains layout orchestration and resize mechanics.

4. **State management layer**
   - The app uses provider-style state containers in `lib/providers/`.
   - The major state domains are:
     - `workspace_provider.dart`: current workspace/files and project context
     - `pane_tree_provider.dart`: the hierarchical editor pane structure
     - `layout_provider.dart`: pane sizing, split ratios, and shell layout state
     - `chat_provider.dart`: AI conversation state and message history
     - `live_content_provider.dart`: synchronized “live” document content
     - `settings_provider.dart`: user preferences and configuration
   - These providers are the main coordination layer between UI widgets and services.

5. **Core domain model**
   - `lib/models/` defines the app’s data structures:
     - `workspace_file.dart`: files in the workspace
     - `pane_node.dart`: tree nodes for the editor layout
     - `drag_payload.dart`: drag-and-drop context between panes/files
     - `chat_session.dart` and `chat_message.dart`: AI conversation state
   - The architecture is centered on a pane tree and workspace files rather than a single monolithic document.

6. **Editor/workspace interaction flow**
   - The file panel exposes workspace files.
   - Files can be opened into the pane tree, which is rendered by `pane_tree_widget.dart`, `split_node_widget.dart`, and `leaf_node_widget.dart`.
   - Editing happens through specialized leaf widgets such as `markdown_editor.dart`, `markdown_preview.dart`, and `pdf_viewer_widget.dart`.
   - The `live_content_provider.dart` suggests that edits propagate into a shared content model used by previews or AI context.

7. **AI/chat subsystem**
   - `lib/services/qwen_service.dart` is the clearest external integration point and likely connects to Qwen-based LLM APIs.
   - `chat_provider.dart` manages assistant state, while `chat_message.dart` and the AI panel widgets render the conversation UI.
   - `context_file_chip.dart` indicates that the assistant can be grounded with selected workspace files, implying file-context injection into prompts.
   - This subsystem is a distinct boundary from the editor: UI events and file context are collected in providers, then sent through the AI service.

8. **Persistence and file services**
   - `lib/services/file_service.dart` handles file system or workspace I/O.
   - `lib/services/persistence_service.dart` likely stores app settings, layout state, and recent workspace/chat state locally.
   - These services sit beneath the providers and keep the UI state durable across sessions.

9. **Rendering and content libraries**
   - The app includes `packages/flutter_math_fork` and `packages/flutter_tex`, which are substantial local packages, not incidental dependencies.
   - `flutter_math_fork` provides TeX/math parsing and rendering in Flutter, with its own parser, encoder, render, and widget layers.
   - `flutter_tex` provides TeX/MathJax-oriented rendering and web/mobile view abstractions.
   - Their presence implies the editor can display mathematical content or TeX-rich documents, which affects the editor and preview architecture.

10. **Theming and visual system**
    - `lib/theme/app_theme.dart` and `app_colors.dart` centralize styling.
    - This is likely a shared visual baseline across the editor, panels, and modal sheets rather than per-widget styling.
    - The presence of dedicated theme files suggests UI consistency is managed centrally.

11. **Platform shells**
    - Android, iOS, macOS, Windows, and Linux folders are standard Flutter host shells.
    - No custom native subsystems are visible beyond standard Flutter entry points like `MainActivity.kt` and platform `AppDelegate` files.
    - The architecture is therefore primarily Flutter-driven, with native code acting as launch/bootstrap only.

12. **Key data flows to reflect in a diagram**
    - Workspace/files flow from `file_service` into `workspace_provider`, then into the file panel and editor panes.
    - Pane/layout state flows through `pane_tree_provider` and `layout_provider` into the editor shell widgets.
    - User edits flow from editor widgets into `live_content_provider`, then back into previews and AI context.
    - Chat context flows from workspace selections and live content into `chat_provider`, then to `qwen_service`, and responses return to the AI panel.
    - Persistent state flows through `persistence_service` to restore settings, layouts, and session data on startup.

13. **Architectural takeaway**
    - The repo is best understood as a modular Flutter workspace editor with three major interaction surfaces: file/workspace navigation, split-pane document editing, and AI assistance.
    - Providers form the state backbone; services form the I/O and AI boundary; widgets are organized by user-facing surface.

Main entry points: [`lib/widgets/layout/app_shell.dart`](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/layout/app_shell.dart) (App shell), [`lib/widgets/editor/pane_tree_widget.dart`](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/editor/pane_tree_widget.dart) (Pane tree), [`lib/widgets/editor/leaf_node_widget.dart`](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/editor/leaf_node_widget.dart) (Leaf views), [`lib/widgets/ai_panel/ai_panel.dart`](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/ai_panel/ai_panel.dart) (AI panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App shell"]
  node_node_main(("Main<br/>entrypoint<br/>[main.dart]"))
  node_node_app["App<br/>root widget<br/>[app.dart]"]
end

subgraph group_group_state["State layer"]
  node_node_workspace_provider["Workspace<br/>provider"]
  node_node_pane_provider["Pane tree state<br/>provider"]
  node_node_layout_provider["Layout state<br/>provider"]
  node_node_chat_provider["Chat state<br/>provider<br/>[chat_provider.dart]"]
  node_node_live_content["Live content<br/>provider"]
  node_node_settings_provider["Prefs<br/>provider"]
  node_node_models["Domain models<br/>data models<br/>[pane_node.dart]"]
end

subgraph group_group_ui["UI surfaces"]
  node_node_shell["App shell<br/>workspace shell<br/>[app_shell.dart]"]
  node_node_file_panel["Files<br/>workspace panel<br/>[file_panel.dart]"]
  node_node_editor_tree["Pane tree<br/>editor layout"]
  node_node_editor_leaf["Leaf views<br/>editor views"]
  node_node_ai_panel["AI panel<br/>assistant panel<br/>[ai_panel.dart]"]
  node_node_settings["Settings<br/>preferences sheet"]
  node_node_theme["Theme<br/>visual system<br/>[app_theme.dart]"]
end

subgraph group_group_services["Services"]
  node_node_file_service["File I/O<br/>[file_service.dart]"]
  node_node_persistence["Persistence"]
  node_node_qwen["Qwen API<br/>llm service<br/>[qwen_service.dart]"]
end

subgraph group_group_packages["Vendored packages"]
  node_node_math_fork["Math fork<br/>vendored package<br/>[flutter_math.dart]"]
  node_node_flutter_tex["Flutter TeX<br/>vendored package<br/>[flutter_tex.dart]"]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"builds"| node_node_shell
node_node_shell -->|"shows"| node_node_file_panel
node_node_shell -->|"shows"| node_node_editor_tree
node_node_shell -->|"shows"| node_node_ai_panel
node_node_shell -->|"opens"| node_node_settings
node_node_shell -->|"uses"| node_node_theme
node_node_file_panel -->|"reads"| node_node_workspace_provider
node_node_file_panel -->|"loads"| node_node_file_service
node_node_editor_tree -->|"reads"| node_node_pane_provider
node_node_editor_tree -->|"reads"| node_node_layout_provider
node_node_editor_tree -->|"nests"| node_node_editor_leaf
node_node_editor_leaf -->|"updates"| node_node_live_content
node_node_editor_leaf -->|"renders"| node_node_math_fork
node_node_editor_leaf -->|"renders"| node_node_flutter_tex
node_node_ai_panel -->|"reads"| node_node_chat_provider
node_node_ai_panel -->|"calls"| node_node_qwen
node_node_ai_panel -->|"uses"| node_node_workspace_provider
node_node_chat_provider -->|"consumes"| node_node_live_content
node_node_workspace_provider -->|"uses"| node_node_models
node_node_pane_provider -->|"uses"| node_node_models
node_node_chat_provider -->|"uses"| node_node_models
node_node_layout_provider -->|"restores"| node_node_persistence
node_node_settings_provider -->|"persists"| node_node_persistence
node_node_workspace_provider -->|"persists"| node_node_persistence
node_node_file_service -.->|"supports"| node_node_persistence

click node_node_main "https://github.com/whyself/ai_native_editor/blob/main/lib/main.dart"
click node_node_app "https://github.com/whyself/ai_native_editor/blob/main/lib/app.dart"
click node_node_shell "https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/layout/app_shell.dart"
click node_node_file_panel "https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/file_panel/file_panel.dart"
click node_node_editor_tree "https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/editor/pane_tree_widget.dart"
click node_node_editor_leaf "https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/editor/leaf_node_widget.dart"
click node_node_ai_panel "https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/ai_panel/ai_panel.dart"
click node_node_settings "https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/settings/settings_sheet.dart"
click node_node_theme "https://github.com/whyself/ai_native_editor/blob/main/lib/theme/app_theme.dart"
click node_node_workspace_provider "https://github.com/whyself/ai_native_editor/blob/main/lib/providers/workspace_provider.dart"
click node_node_pane_provider "https://github.com/whyself/ai_native_editor/blob/main/lib/providers/pane_tree_provider.dart"
click node_node_layout_provider "https://github.com/whyself/ai_native_editor/blob/main/lib/providers/layout_provider.dart"
click node_node_chat_provider "https://github.com/whyself/ai_native_editor/blob/main/lib/providers/chat_provider.dart"
click node_node_live_content "https://github.com/whyself/ai_native_editor/blob/main/lib/providers/live_content_provider.dart"
click node_node_settings_provider "https://github.com/whyself/ai_native_editor/blob/main/lib/providers/settings_provider.dart"
click node_node_models "https://github.com/whyself/ai_native_editor/blob/main/lib/models/pane_node.dart"
click node_node_file_service "https://github.com/whyself/ai_native_editor/blob/main/lib/services/file_service.dart"
click node_node_persistence "https://github.com/whyself/ai_native_editor/blob/main/lib/services/persistence_service.dart"
click node_node_qwen "https://github.com/whyself/ai_native_editor/blob/main/lib/services/qwen_service.dart"
click node_node_math_fork "https://github.com/whyself/ai_native_editor/blob/main/packages/flutter_math_fork/lib/flutter_math.dart"
click node_node_flutter_tex "https://github.com/whyself/ai_native_editor/blob/main/packages/flutter_tex/lib/flutter_tex.dart"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_app toneBlue
class node_node_workspace_provider,node_node_pane_provider,node_node_layout_provider,node_node_chat_provider,node_node_live_content,node_node_settings_provider,node_node_models toneAmber
class node_node_shell,node_node_file_panel,node_node_editor_tree,node_node_editor_leaf,node_node_ai_panel,node_node_settings,node_node_theme toneMint
class node_node_file_service,node_node_persistence,node_node_qwen toneRose
class node_node_math_fork,node_node_flutter_tex toneIndigo
```

## Components

### App shell

Flutter application entrypoints and host shell.

- [Main](https://github.com/whyself/ai_native_editor/blob/main/lib/main.dart): entrypoint · Flutter bootstrap and app launch. · `lib/main.dart`
- [App](https://github.com/whyself/ai_native_editor/blob/main/lib/app.dart): root widget · Top-level application composition and routing. · `lib/app.dart`

### State layer

Providers and domain models coordinating the app.

- [Workspace](https://github.com/whyself/ai_native_editor/blob/main/lib/providers/workspace_provider.dart): provider · Current workspace, files, and project context. · `lib/providers/workspace_provider.dart`
- [Pane tree state](https://github.com/whyself/ai_native_editor/blob/main/lib/providers/pane_tree_provider.dart): provider · Hierarchical editor pane structure. · `lib/providers/pane_tree_provider.dart`
- [Layout state](https://github.com/whyself/ai_native_editor/blob/main/lib/providers/layout_provider.dart): provider · Split ratios, pane sizes, and shell layout. · `lib/providers/layout_provider.dart`
- [Chat state](https://github.com/whyself/ai_native_editor/blob/main/lib/providers/chat_provider.dart): provider · Assistant conversation state and message history. · `lib/providers/chat_provider.dart`
- [Live content](https://github.com/whyself/ai_native_editor/blob/main/lib/providers/live_content_provider.dart): provider · Shared synchronized document content. · `lib/providers/live_content_provider.dart`
- [Prefs](https://github.com/whyself/ai_native_editor/blob/main/lib/providers/settings_provider.dart): provider · User preferences and configuration state. · `lib/providers/settings_provider.dart`
- [Domain models](https://github.com/whyself/ai_native_editor/blob/main/lib/models/pane_node.dart): data models · Workspace files, panes, chat sessions, and drag payloads. · `lib/models/pane_node.dart`

### UI surfaces

Primary user-facing widget boundaries.

- [App shell](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/layout/app_shell.dart): workspace shell · Composes the major panes and layout regions. · `lib/widgets/layout/app_shell.dart`
- [Files](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/file_panel/file_panel.dart): workspace panel · Workspace file navigation and open-file entrypoint. · `lib/widgets/file_panel/file_panel.dart`
- [Pane tree](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/editor/pane_tree_widget.dart): editor layout · Split-pane editor tree and leaf composition. · `lib/widgets/editor/pane_tree_widget.dart`
- [Leaf views](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/editor/leaf_node_widget.dart): editor views · Specialized editors and previews for file content. · `lib/widgets/editor/leaf_node_widget.dart`
- [AI panel](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/ai_panel/ai_panel.dart): assistant panel · Chat and assistant interaction surface. · `lib/widgets/ai_panel/ai_panel.dart`
- [Settings](https://github.com/whyself/ai_native_editor/blob/main/lib/widgets/settings/settings_sheet.dart): preferences sheet · Modal or side sheet for app configuration. · `lib/widgets/settings/settings_sheet.dart`
- [Theme](https://github.com/whyself/ai_native_editor/blob/main/lib/theme/app_theme.dart): visual system · Shared colors and app-wide styling. · `lib/theme/app_theme.dart`

### Services

Persistence, file I/O, and AI integration.

- [File I/O](https://github.com/whyself/ai_native_editor/blob/main/lib/services/file_service.dart): service · Workspace and filesystem access. · `lib/services/file_service.dart`
- [Persistence](https://github.com/whyself/ai_native_editor/blob/main/lib/services/persistence_service.dart): service · Local storage for settings, layout, and session state. · `lib/services/persistence_service.dart`
- [Qwen API](https://github.com/whyself/ai_native_editor/blob/main/lib/services/qwen_service.dart): llm service · External AI integration for chat generation. · `lib/services/qwen_service.dart`

### Vendored packages

Local Flutter packages used for math and TeX rendering.

- [Math fork](https://github.com/whyself/ai_native_editor/blob/main/packages/flutter_math_fork/lib/flutter_math.dart): vendored package · Local package for Flutter math rendering and TeX parsing. · `packages/flutter_math_fork/lib/flutter_math.dart`
- [Flutter TeX](https://github.com/whyself/ai_native_editor/blob/main/packages/flutter_tex/lib/flutter_tex.dart): vendored package · Local package for TeX/MathJax-oriented rendering views. · `packages/flutter_tex/lib/flutter_tex.dart`

## Connections

- Main → App: boots · Main starts the root app widget.
- App → App shell: builds · The root app composes the main workspace shell.
- App shell → Files: shows · Shell includes workspace navigation.
- App shell → Pane tree: shows · Shell includes the split-pane editor region.
- App shell → AI panel: shows · Shell includes the assistant surface.
- App shell → Settings: opens · Shell can present settings UI.
- App shell → Theme: uses · Shell and subviews share the app theme.
- Files → Workspace: reads · File panel renders workspace contents.
- Files → File I/O: loads · Workspace files are sourced from file I/O.
- Pane tree → Pane tree state: reads · Editor tree reflects pane hierarchy state.
- Pane tree → Layout state: reads · Editor tree follows layout and split state.
- Pane tree → Leaf views: nests · Pane tree delegates to leaf views for content.
- Leaf views → Live content: updates · Edits flow into the shared live content model.
- Leaf views → Math fork: renders · Editor content can use math rendering.
- Leaf views → Flutter TeX: renders · Editor content can use TeX-oriented rendering.
- AI panel → Chat state: reads · AI panel is driven by chat state.
- AI panel → Qwen API: calls · Assistant requests are sent to the LLM service.
- AI panel → Workspace: uses · Chat context can include selected workspace files.
- Chat state → Live content: consumes · Assistant context can be grounded in live document content.
- Workspace → Domain models: uses · Workspace state is built on the domain model types.
- Pane tree state → Domain models: uses · Pane hierarchy relies on pane node models.
- Chat state → Domain models: uses · Chat state uses session and message models.
- Layout state → Persistence: restores · Layout state is persisted across sessions.
- Prefs → Persistence: persists · Preferences are saved locally.
- Workspace → Persistence: persists · Workspace/session context can be restored locally.
- File I/O → Persistence: supports · File access is complemented by persisted app state.
