How whyself/ai_native_editor works
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: app_shell.dart App shell · pane_tree_widget.dart Pane tree · leaf_node_widget.dart Leaf views · ai_panel.dart AI panel
Components 21
App shell
Flutter application entrypoints and host shell.
State layer
Providers and domain models coordinating the app.
- Workspace · Current workspace, files, and project context.
lib/providers/workspace_provider.dart - Pane tree state · Hierarchical editor pane structure.
lib/providers/pane_tree_provider.dart - Layout state · Split ratios, pane sizes, and shell layout.
lib/providers/layout_provider.dart - Chat state · Assistant conversation state and message history.
lib/providers/chat_provider.dart - Live content · Shared synchronized document content.
lib/providers/live_content_provider.dart - Prefs · User preferences and configuration state.
lib/providers/settings_provider.dart - Domain models · Workspace files, panes, chat sessions, and drag payloads.
lib/models/pane_node.dart
UI surfaces
Primary user-facing widget boundaries.
- App shell · Composes the major panes and layout regions.
lib/widgets/layout/app_shell.dart - Files · Workspace file navigation and open-file entrypoint.
lib/widgets/file_panel/file_panel.dart - Pane tree · Split-pane editor tree and leaf composition.
lib/widgets/editor/pane_tree_widget.dart - Leaf views · Specialized editors and previews for file content.
lib/widgets/editor/leaf_node_widget.dart - AI panel · Chat and assistant interaction surface.
lib/widgets/ai_panel/ai_panel.dart - Settings · Modal or side sheet for app configuration.
lib/widgets/settings/settings_sheet.dart - Theme · Shared colors and app-wide styling.
lib/theme/app_theme.dart
Services
Persistence, file I/O, and AI integration.
- File I/O · Workspace and filesystem access.
lib/services/file_service.dart - Persistence · Local storage for settings, layout, and session state.
lib/services/persistence_service.dart - Qwen API · External AI integration for chat generation.
lib/services/qwen_service.dart
Vendored packages
Local Flutter packages used for math and TeX rendering.
- Math fork · Local package for Flutter math rendering and TeX parsing.
packages/flutter_math_fork/lib/flutter_math.dart - Flutter TeX · Local package for TeX/MathJax-oriented rendering views.
packages/flutter_tex/lib/flutter_tex.dart
Connections 26
- 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.