# the-hieusss/misa architecture

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

- Interactive diagram: https://gitdiagram.com/the-hieusss/misa
- Repository: https://github.com/the-hieusss/misa

## Overview

M.I.S.A. is a local macOS floating assistant: users ask in its chat or drop files, Swift interprets requests and dispatches actions, and replies return to the web UI. The graph also captures the documented file workflows and the customizable animated assistant. The action-dispatch links are supported by Brain’s indexed references; some action internals and the full native/web message handling were not sampled, so those details are not inferred.

Main entry points: [`app/Sources/MISA/Brain.swift`](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Brain.swift) (Request Router), [`web/src/App.tsx`](https://github.com/the-hieusss/misa/blob/main/web/src/App.tsx) (Chat Interface), [`app/Sources/MISA/MisaController.swift`](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/MisaController.swift) (Window Controller), [`web/src/misa/mecha-halo.tsx`](https://github.com/the-hieusss/misa/blob/main/web/src/misa/mecha-halo.tsx) (Animated Halo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["macOS Shell"]
  node_controller["Window Controller"]
  node_delegate["App Lifecycle<br/>[AppDelegate.swift]"]
  node_webview["Web UI Host<br/>[DropWebView.swift]"]
  node_scheme["Bundle UI Server"]
end

subgraph group_actions["Assistant Actions"]
  node_brain["Request Router<br/>[Brain.swift]"]
  node_reply["Reply and Confirm<br/>[Reply.swift]"]
end

subgraph group_ui["Chat and Appearance"]
  node_app["Chat Interface<br/>[App.tsx]"]
  node_bridge["Native Bridge<br/>[bridge.ts]"]
  node_halo["Animated Halo<br/>[mecha-halo.tsx]"]
  node_eye["Eye Renderer<br/>[eye-parts.tsx]"]
  node_shell["Shell Geometry<br/>[shell-parts.tsx]"]
  node_skin["Appearance Catalog<br/>[skin.ts]"]
  node_wardrobe["Wardrobe Editor<br/>[wardrobe.tsx]"]
  node_timerui["Timer Ring<br/>[timer-ring.tsx]"]
end

subgraph group_features["File and Utility Features"]
  node_move["File Moves<br/>[MoveFiles.swift]"]
  node_convert["File Conversion<br/>[Convert.swift]"]
  node_copyai["AI Text Copy<br/>[CopyForAI.swift]"]
  node_canvas["Canvas Prep<br/>[CanvasPrep.swift]"]
  node_files["File Utilities<br/>[Files.swift]"]
  node_calculator["Calculator<br/>[Calculator.swift]"]
  node_units["Unit Conversion"]
  node_focus["Focus Timer<br/>[FocusTimer.swift]"]
  node_screenshots["Screenshot Tidy<br/>[Screenshots.swift]"]
  node_downloads["Downloads Tidy"]
  node_apps["App Launcher<br/>[AppLauncher.swift]"]
  node_webopen["Web Opener<br/>[WebOpener.swift]"]
  node_trash["Trash Actions<br/>[TrashBin.swift]"]
  node_disposable["Disposable Files"]
  node_disk["Disk Report<br/>[DiskReport.swift]"]
end

node_user(("User"))

node_user -.->|"asks or drops"| node_app
node_app -->|"sends requests"| node_bridge
node_bridge -.->|"messages native"| node_controller
node_controller -->|"routes requests"| node_brain
node_controller -->|"hosts UI"| node_webview
node_controller -->|"serves bundled UI"| node_scheme
node_delegate -->|"creates controller"| node_controller
node_brain -->|"dispatches moves"| node_move
node_brain -->|"dispatches conversion"| node_convert
node_brain -->|"dispatches text copy"| node_copyai
node_brain -->|"dispatches prep"| node_canvas
node_brain -->|"dispatches math"| node_calculator
node_brain -->|"dispatches conversion"| node_units
node_brain -->|"dispatches timer"| node_focus
node_brain -->|"dispatches tidy"| node_screenshots
node_brain -->|"dispatches tidy"| node_downloads
node_brain -->|"dispatches app control"| node_apps
node_brain -->|"dispatches web opening"| node_webopen
node_brain -->|"dispatches trash"| node_trash
node_brain -->|"dispatches file marking"| node_disposable
node_brain -->|"dispatches report"| node_disk
node_brain -->|"returns response"| node_reply
node_app -->|"renders assistant"| node_halo
node_app -->|"renders countdown"| node_timerui
node_app -->|"opens editor"| node_wardrobe
node_halo -->|"uses geometry"| node_shell
node_halo -->|"reads appearance"| node_skin
node_halo -.->|"renders eye"| node_eye
node_wardrobe -->|"previews parts"| node_shell
node_wardrobe -->|"previews eye parts"| node_eye
node_wardrobe -->|"reads options"| node_skin

click node_controller "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/MisaController.swift"
click node_delegate "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/AppDelegate.swift"
click node_webview "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/DropWebView.swift"
click node_scheme "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/BundleSchemeHandler.swift"
click node_brain "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Brain.swift"
click node_reply "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Reply.swift"
click node_app "https://github.com/the-hieusss/misa/blob/main/web/src/App.tsx"
click node_bridge "https://github.com/the-hieusss/misa/blob/main/web/src/bridge.ts"
click node_halo "https://github.com/the-hieusss/misa/blob/main/web/src/misa/mecha-halo.tsx"
click node_eye "https://github.com/the-hieusss/misa/blob/main/web/src/misa/eye-parts.tsx"
click node_shell "https://github.com/the-hieusss/misa/blob/main/web/src/misa/shell-parts.tsx"
click node_skin "https://github.com/the-hieusss/misa/blob/main/web/src/misa/skin.ts"
click node_wardrobe "https://github.com/the-hieusss/misa/blob/main/web/src/misa/wardrobe.tsx"
click node_timerui "https://github.com/the-hieusss/misa/blob/main/web/src/misa/timer-ring.tsx"
click node_move "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/MoveFiles.swift"
click node_convert "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Convert.swift"
click node_copyai "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/CopyForAI.swift"
click node_canvas "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/CanvasPrep.swift"
click node_files "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Files.swift"
click node_calculator "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Calculator.swift"
click node_units "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/UnitConverter.swift"
click node_focus "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/FocusTimer.swift"
click node_screenshots "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Screenshots.swift"
click node_downloads "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/DownloadsTidy.swift"
click node_apps "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/AppLauncher.swift"
click node_webopen "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/WebOpener.swift"
click node_trash "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/TrashBin.swift"
click node_disposable "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/DisposableActions.swift"
click node_disk "https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/DiskReport.swift"

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_controller,node_delegate,node_webview,node_scheme,node_user toneBlue
class node_brain,node_reply toneAmber
class node_app,node_bridge,node_halo,node_eye,node_shell,node_skin,node_wardrobe,node_timerui toneMint
class node_move,node_convert,node_copyai,node_canvas,node_files,node_calculator,node_units,node_focus,node_screenshots,node_downloads,node_apps,node_webopen,node_trash,node_disposable,node_disk toneRose
```

## Components

### macOS Shell

- [Window Controller](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/MisaController.swift): `app/Sources/MISA/MisaController.swift`
- [App Lifecycle](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/AppDelegate.swift): `app/Sources/MISA/AppDelegate.swift`
- [Web UI Host](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/DropWebView.swift): `app/Sources/MISA/DropWebView.swift`
- [Bundle UI Server](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/BundleSchemeHandler.swift): `app/Sources/MISA/BundleSchemeHandler.swift`

### Assistant Actions

- [Request Router](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Brain.swift): `app/Sources/MISA/Brain.swift`
- [Reply and Confirm](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Reply.swift): `app/Sources/MISA/Actions/Reply.swift`

### Chat and Appearance

- [Chat Interface](https://github.com/the-hieusss/misa/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Native Bridge](https://github.com/the-hieusss/misa/blob/main/web/src/bridge.ts): `web/src/bridge.ts`
- [Animated Halo](https://github.com/the-hieusss/misa/blob/main/web/src/misa/mecha-halo.tsx): `web/src/misa/mecha-halo.tsx`
- [Eye Renderer](https://github.com/the-hieusss/misa/blob/main/web/src/misa/eye-parts.tsx): `web/src/misa/eye-parts.tsx`
- [Shell Geometry](https://github.com/the-hieusss/misa/blob/main/web/src/misa/shell-parts.tsx): `web/src/misa/shell-parts.tsx`
- [Appearance Catalog](https://github.com/the-hieusss/misa/blob/main/web/src/misa/skin.ts): `web/src/misa/skin.ts`
- [Wardrobe Editor](https://github.com/the-hieusss/misa/blob/main/web/src/misa/wardrobe.tsx): `web/src/misa/wardrobe.tsx`
- [Timer Ring](https://github.com/the-hieusss/misa/blob/main/web/src/misa/timer-ring.tsx): `web/src/misa/timer-ring.tsx`

### File and Utility Features

- [File Moves](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/MoveFiles.swift): `app/Sources/MISA/Actions/MoveFiles.swift`
- [File Conversion](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Convert.swift): `app/Sources/MISA/Actions/Convert.swift`
- [AI Text Copy](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/CopyForAI.swift): `app/Sources/MISA/Actions/CopyForAI.swift`
- [Canvas Prep](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/CanvasPrep.swift): `app/Sources/MISA/Actions/CanvasPrep.swift`
- [File Utilities](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Files.swift): `app/Sources/MISA/Actions/Files.swift`
- [Calculator](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Calculator.swift): `app/Sources/MISA/Actions/Calculator.swift`
- [Unit Conversion](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/UnitConverter.swift): `app/Sources/MISA/Actions/UnitConverter.swift`
- [Focus Timer](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/FocusTimer.swift): `app/Sources/MISA/Actions/FocusTimer.swift`
- [Screenshot Tidy](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/Screenshots.swift): `app/Sources/MISA/Actions/Screenshots.swift`
- [Downloads Tidy](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/DownloadsTidy.swift): `app/Sources/MISA/Actions/DownloadsTidy.swift`
- [App Launcher](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/AppLauncher.swift): `app/Sources/MISA/Actions/AppLauncher.swift`
- [Web Opener](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/WebOpener.swift): `app/Sources/MISA/Actions/WebOpener.swift`
- [Trash Actions](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/TrashBin.swift): `app/Sources/MISA/Actions/TrashBin.swift`
- [Disposable Files](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/DisposableActions.swift): `app/Sources/MISA/Actions/DisposableActions.swift`
- [Disk Report](https://github.com/the-hieusss/misa/blob/main/app/Sources/MISA/Actions/DiskReport.swift): `app/Sources/MISA/Actions/DiskReport.swift`

### Other components

- **User**

## Connections

- User → Chat Interface: asks or drops
- Chat Interface → Native Bridge: sends requests (evidence: `web/src/App.tsx`)
- Native Bridge → Window Controller: messages native
- Window Controller → Request Router: routes requests (evidence: `app/Sources/MISA/MisaController.swift`)
- Window Controller → Web UI Host: hosts UI (evidence: `app/Sources/MISA/MisaController.swift`)
- Window Controller → Bundle UI Server: serves bundled UI (evidence: `app/Sources/MISA/MisaController.swift`)
- App Lifecycle → Window Controller: creates controller (evidence: `app/Sources/MISA/AppDelegate.swift`)
- Request Router → File Moves: dispatches moves (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → File Conversion: dispatches conversion (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → AI Text Copy: dispatches text copy (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Canvas Prep: dispatches prep (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Calculator: dispatches math (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Unit Conversion: dispatches conversion (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Focus Timer: dispatches timer (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Screenshot Tidy: dispatches tidy (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Downloads Tidy: dispatches tidy (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → App Launcher: dispatches app control (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Web Opener: dispatches web opening (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Trash Actions: dispatches trash (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Disposable Files: dispatches file marking (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Disk Report: dispatches report (evidence: `app/Sources/MISA/Brain.swift`)
- Request Router → Reply and Confirm: returns response (evidence: `app/Sources/MISA/Brain.swift`)
- Chat Interface → Animated Halo: renders assistant (evidence: `web/src/App.tsx`)
- Chat Interface → Timer Ring: renders countdown (evidence: `web/src/App.tsx`)
- Chat Interface → Wardrobe Editor: opens editor (evidence: `web/src/App.tsx`)
- Animated Halo → Shell Geometry: uses geometry (evidence: `web/src/misa/mecha-halo.tsx`)
- Animated Halo → Appearance Catalog: reads appearance (evidence: `web/src/misa/mecha-halo.tsx`)
- Animated Halo → Eye Renderer: renders eye
- Wardrobe Editor → Shell Geometry: previews parts (evidence: `web/src/misa/wardrobe.tsx`)
- Wardrobe Editor → Eye Renderer: previews eye parts (evidence: `web/src/misa/wardrobe.tsx`)
- Wardrobe Editor → Appearance Catalog: reads options (evidence: `web/src/misa/wardrobe.tsx`)
