# macchiato1239/desktopbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/macchiato1239/desktopbuddy
- Repository: https://github.com/macchiato1239/desktopbuddy

## Overview

Desktop Buddy is a macOS desktop app for importing local images or choosing built-in assets, displaying each as an always-on-top movable buddy, and adjusting its position and size. The documented workflow runs through the Flutter interface and a native macOS overlay implementation. README behavior supports the UI stages, while sampled AppDelegate code confirms method-channel operations, panel management, image loading and frame notifications. Flutter source files were not sampled, so detailed UI-to-channel wiring is not asserted.

Main entry points: [`lib/main.dart`](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/main.dart) (App interface), [`macos/Runner/AppDelegate.swift`](https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift) (Native app delegate), [`lib/library.dart`](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/library.dart) (Built-in library), [`lib/buttons.dart`](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/buttons.dart) (Import controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter_ui["Flutter interface"]
  node_flutter_app["App interface<br/>[main.dart]"]
  node_asset_library["Built-in library<br/>[library.dart]"]
  node_import_controls["Import controls<br/>[buttons.dart]"]
  node_layer_list["Layer list<br/>[layer.dart]"]
  node_property_controls["Buddy properties<br/>[layer.dart]"]
  node_background_ui["Background UI<br/>[background.dart]"]
  node_focus_ui["Focus handling<br/>[focus.dart]"]
end

subgraph group_buddy_workflow["Buddy workflow"]
  node_local_files["Local image files"]
  node_bundled_assets["Bundled assets"]
end

subgraph group_macos_runtime["macOS overlays"]
  node_channel["Method channel<br/>[AppDelegate.swift]"]
  node_native_app["Native app delegate<br/>[AppDelegate.swift]"]
  node_overlay_panels["Floating overlays<br/>[AppDelegate.swift]"]
  node_image_display["Image display<br/>[AppDelegate.swift]"]
end

node_user(("User"))

node_user -->|"uses"| node_flutter_app
node_user -->|"chooses"| node_local_files
node_asset_library -->|"offers assets"| node_flutter_app
node_import_controls -->|"offers import"| node_flutter_app
node_layer_list -->|"shows layers"| node_flutter_app
node_property_controls -->|"edits properties"| node_flutter_app
node_flutter_app -->|"dispatches commands"| node_channel
node_channel -->|"delivers calls"| node_native_app
node_native_app -->|"creates and updates"| node_overlay_panels
node_native_app -->|"opens selection dialog"| node_local_files
node_native_app -->|"loads built-in image"| node_bundled_assets
node_native_app -->|"loads selected image"| node_image_display
node_image_display -->|"renders into"| node_overlay_panels
node_overlay_panels -->|"sends frame updates"| node_channel
node_channel -->|"returns notifications"| node_flutter_app

click node_flutter_app "https://github.com/macchiato1239/desktopbuddy/blob/main/lib/main.dart"
click node_asset_library "https://github.com/macchiato1239/desktopbuddy/blob/main/lib/library.dart"
click node_import_controls "https://github.com/macchiato1239/desktopbuddy/blob/main/lib/buttons.dart"
click node_layer_list "https://github.com/macchiato1239/desktopbuddy/blob/main/lib/layer.dart"
click node_property_controls "https://github.com/macchiato1239/desktopbuddy/blob/main/lib/layer.dart"
click node_background_ui "https://github.com/macchiato1239/desktopbuddy/blob/main/lib/background.dart"
click node_focus_ui "https://github.com/macchiato1239/desktopbuddy/blob/main/lib/focus.dart"
click node_channel "https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift"
click node_native_app "https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift"
click node_overlay_panels "https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift"
click node_image_display "https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift"
click node_bundled_assets "https://github.com/macchiato1239/desktopbuddy/tree/main/assets"

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_flutter_app,node_asset_library,node_import_controls,node_layer_list,node_property_controls,node_background_ui,node_focus_ui,node_user toneBlue
class node_local_files,node_bundled_assets toneAmber
class node_channel,node_native_app,node_overlay_panels,node_image_display toneMint
```

## Components

### Flutter interface

- [App interface](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/main.dart): `lib/main.dart`
- [Built-in library](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/library.dart): `lib/library.dart`
- [Import controls](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/buttons.dart): `lib/buttons.dart`
- [Layer list](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/layer.dart): `lib/layer.dart`
- [Buddy properties](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/layer.dart): `lib/layer.dart`
- [Background UI](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/background.dart): `lib/background.dart`
- [Focus handling](https://github.com/macchiato1239/desktopbuddy/blob/main/lib/focus.dart): `lib/focus.dart`

### Buddy workflow

- **Local image files**
- [Bundled assets](https://github.com/macchiato1239/desktopbuddy/tree/main/assets): `assets`

### macOS overlays

- [Method channel](https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift): `macos/Runner/AppDelegate.swift`
- [Native app delegate](https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift): `macos/Runner/AppDelegate.swift`
- [Floating overlays](https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift): `macos/Runner/AppDelegate.swift`
- [Image display](https://github.com/macchiato1239/desktopbuddy/blob/main/macos/Runner/AppDelegate.swift): `macos/Runner/AppDelegate.swift`

### Other components

- **User**

## Connections

- User → App interface: uses
- User → Local image files: chooses
- Built-in library → App interface: offers assets
- Import controls → App interface: offers import
- Layer list → App interface: shows layers
- Buddy properties → App interface: edits properties
- App interface → Method channel: dispatches commands
- Method channel → Native app delegate: delivers calls
- Native app delegate → Floating overlays: creates and updates
- Native app delegate → Local image files: opens selection dialog
- Native app delegate → Bundled assets: loads built-in image
- Native app delegate → Image display: loads selected image
- Image display → Floating overlays: renders into
- Floating overlays → Method channel: sends frame updates
- Method channel → App interface: returns notifications