# nizwar/avo architecture

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

- Interactive diagram: https://gitdiagram.com/nizwar/avo
- Repository: https://github.com/nizwar/avo

## Overview

Avo runs AOSP Android in a per-user Hypervisor.framework VM and presents Android apps as native Mac windows. The main workflow is Control Panel or app-window requests → daemon → VM engine → Android guest, with frames and input returned to the window host. The README also documents app installation, configurable device and graphics settings, storage choices, and Mac/Android integrations. Relationships for unsampled subsystems are included only where the README or indexed source references support them; the graph does not imply unshown internal call order.

Main entry points: [`host/AvoKit/Sources/AvoDaemonCore/DaemonCore.swift`](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/DaemonCore.swift) (Runtime daemon), [`engine/hvf/vmm/src/main.rs`](https://github.com/nizwar/avo/blob/main/engine/hvf/vmm/src/main.rs) (AOSP Cuttlefish VM), [`host/AvoKit/Sources/AvoKit/DaemonClient.swift`](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/DaemonClient.swift) (Daemon client), [`host/AvoWindowHost/AndroidWindowController.swift`](https://github.com/nizwar/avo/blob/main/host/AvoWindowHost/AndroidWindowController.swift) (Android app windows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Mac apps and daemon"]
  node_control["Control Panel"]
  node_daemon["Runtime daemon<br/>[DaemonCore.swift]"]
  node_menu["Menu bar"]
  node_image["Android image setup<br/>[AndroidImage.swift]"]
  node_storage[("Data locations")]
  node_window_host["Android app windows"]
  node_display["Display view<br/>[DisplayView.swift]"]
  node_renderer["Metal renderer"]
  node_host_agent["Guest host agent<br/>[HostAgent.swift]"]
  node_screen_text["Screen translation"]
end

subgraph group_engine["VM engine"]
  node_vmm_engine["VMM engine<br/>[VMMEngine.swift]"]
end

subgraph group_guest["Android guest"]
  node_android_vm["AOSP Cuttlefish VM<br/>[main.rs]"]
  node_bridge["Guest bridge agent<br/>[Bridge.java]"]
  node_guest_display["Guest displays"]
  node_notifications["Notification bridge"]
  node_apps["Android apps"]
end

subgraph group_shared["Configuration and protocol"]
  node_daemon_client["Daemon client<br/>[DaemonClient.swift]"]
  node_vm_config["VM configuration<br/>[VMConfig.swift]"]
  node_device_profile["Device profiles"]
  node_paths["User data paths<br/>[AvoPaths.swift]"]
  node_app_registry[("App registry<br/>[AppRecord.swift]")]
  node_protocol["Host protocol<br/>[AvoProtocol.swift]"]
end

node_user(("Mac user"))
node_metal["Apple Metal"]
node_adbd["Android adbd"]

node_user -->|"manages Android"| node_control
node_control -->|"sends XPC requests"| node_daemon_client
node_window_host -->|"sends XPC input"| node_daemon_client
node_menu -->|"controls VM"| node_daemon
node_daemon_client -.->|"calls daemon"| node_daemon
node_daemon -->|"spawns engine"| node_vmm_engine
node_daemon -.->|"manages image"| node_image
node_control -.->|"edits settings"| node_vm_config
node_vm_config -.->|"configures VM"| node_vmm_engine
node_device_profile -->|"sets boot properties"| node_vmm_engine
node_storage -->|"uses data paths"| node_paths
node_daemon -.->|"manages data"| node_storage
node_window_host -->|"uses messages"| node_protocol
node_daemon_client -.->|"uses messages"| node_protocol
node_window_host -->|"routes frames"| node_display
node_display -->|"renders frames"| node_renderer
node_android_vm -->|"renders via gfxstream"| node_metal
node_android_vm -->|"runs apps"| node_apps
node_android_vm -->|"provides virtio devices"| node_guest_display
node_bridge -->|"starts display service"| node_guest_display
node_bridge -->|"starts notification bridge"| node_notifications
node_guest_display -->|"launches on displays"| node_apps
node_android_vm -->|"provides ADB"| node_adbd
node_daemon -.->|"coordinates guest agent"| node_host_agent
node_host_agent -.->|"communicates with guest"| node_bridge
node_daemon -.->|"supports translation"| node_screen_text
node_android_vm -->|"serves app displays"| node_apps

click node_control "https://github.com/nizwar/avo/blob/main/host/Avo/ControlPanelModel.swift"
click node_daemon "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/DaemonCore.swift"
click node_menu "https://github.com/nizwar/avo/blob/main/host/AvoDaemon/MenuBarController.swift"
click node_daemon_client "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/DaemonClient.swift"
click node_vmm_engine "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/VMMEngine.swift"
click node_vm_config "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/VMConfig.swift"
click node_device_profile "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/DeviceProfile.swift"
click node_image "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/AndroidImage.swift"
click node_storage "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/StorageLocations.swift"
click node_paths "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/AvoPaths.swift"
click node_app_registry "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/AppRecord.swift"
click node_window_host "https://github.com/nizwar/avo/blob/main/host/AvoWindowHost/AndroidWindowController.swift"
click node_display "https://github.com/nizwar/avo/blob/main/host/AvoWindowHost/DisplayView.swift"
click node_renderer "https://github.com/nizwar/avo/blob/main/host/AvoWindowHost/MetalRenderer.swift"
click node_protocol "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoProtocol/AvoProtocol.swift"
click node_host_agent "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/HostAgent.swift"
click node_android_vm "https://github.com/nizwar/avo/blob/main/engine/hvf/vmm/src/main.rs"
click node_bridge "https://github.com/nizwar/avo/blob/main/guest/bridge-agent/src/com/avodroid/bridge/Bridge.java"
click node_guest_display "https://github.com/nizwar/avo/blob/main/guest/bridge-agent/src/com/avodroid/bridge/display/DisplayController.java"
click node_notifications "https://github.com/nizwar/avo/blob/main/guest/bridge-agent/src/com/avodroid/bridge/notify/NotificationBridge.java"
click node_screen_text "https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/ScreenTextEngine.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_control,node_daemon,node_menu,node_image,node_storage,node_window_host,node_display,node_renderer,node_host_agent,node_screen_text,node_user toneBlue
class node_vmm_engine toneAmber
class node_android_vm,node_bridge,node_guest_display,node_notifications,node_apps toneMint
class node_daemon_client,node_vm_config,node_device_profile,node_paths,node_app_registry,node_protocol toneRose
class node_metal,node_adbd toneIndigo
```

## Components

### Mac apps and daemon

- [Control Panel](https://github.com/nizwar/avo/blob/main/host/Avo/ControlPanelModel.swift): `host/Avo/ControlPanelModel.swift`
- [Runtime daemon](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/DaemonCore.swift): `host/AvoKit/Sources/AvoDaemonCore/DaemonCore.swift`
- [Menu bar](https://github.com/nizwar/avo/blob/main/host/AvoDaemon/MenuBarController.swift): `host/AvoDaemon/MenuBarController.swift`
- [Android image setup](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/AndroidImage.swift): `host/AvoKit/Sources/AvoDaemonCore/AndroidImage.swift`
- [Data locations](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/StorageLocations.swift): `host/AvoKit/Sources/AvoDaemonCore/StorageLocations.swift`
- [Android app windows](https://github.com/nizwar/avo/blob/main/host/AvoWindowHost/AndroidWindowController.swift): `host/AvoWindowHost/AndroidWindowController.swift`
- [Display view](https://github.com/nizwar/avo/blob/main/host/AvoWindowHost/DisplayView.swift): `host/AvoWindowHost/DisplayView.swift`
- [Metal renderer](https://github.com/nizwar/avo/blob/main/host/AvoWindowHost/MetalRenderer.swift): `host/AvoWindowHost/MetalRenderer.swift`
- [Guest host agent](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/HostAgent.swift): `host/AvoKit/Sources/AvoDaemonCore/HostAgent.swift`
- [Screen translation](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/ScreenTextEngine.swift): `host/AvoKit/Sources/AvoDaemonCore/ScreenTextEngine.swift`

### VM engine

- [VMM engine](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoDaemonCore/VMMEngine.swift): `host/AvoKit/Sources/AvoDaemonCore/VMMEngine.swift`

### Android guest

- [AOSP Cuttlefish VM](https://github.com/nizwar/avo/blob/main/engine/hvf/vmm/src/main.rs): `engine/hvf/vmm/src/main.rs`
- [Guest bridge agent](https://github.com/nizwar/avo/blob/main/guest/bridge-agent/src/com/avodroid/bridge/Bridge.java): `guest/bridge-agent/src/com/avodroid/bridge/Bridge.java`
- [Guest displays](https://github.com/nizwar/avo/blob/main/guest/bridge-agent/src/com/avodroid/bridge/display/DisplayController.java): `guest/bridge-agent/src/com/avodroid/bridge/display/DisplayController.java`
- [Notification bridge](https://github.com/nizwar/avo/blob/main/guest/bridge-agent/src/com/avodroid/bridge/notify/NotificationBridge.java): `guest/bridge-agent/src/com/avodroid/bridge/notify/NotificationBridge.java`
- **Android apps**

### Configuration and protocol

- [Daemon client](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/DaemonClient.swift): `host/AvoKit/Sources/AvoKit/DaemonClient.swift`
- [VM configuration](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/VMConfig.swift): `host/AvoKit/Sources/AvoKit/VMConfig.swift`
- [Device profiles](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/DeviceProfile.swift): `host/AvoKit/Sources/AvoKit/DeviceProfile.swift`
- [User data paths](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/AvoPaths.swift): `host/AvoKit/Sources/AvoKit/AvoPaths.swift`
- [App registry](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoKit/AppRecord.swift): `host/AvoKit/Sources/AvoKit/AppRecord.swift`
- [Host protocol](https://github.com/nizwar/avo/blob/main/host/AvoKit/Sources/AvoProtocol/AvoProtocol.swift): `host/AvoKit/Sources/AvoProtocol/AvoProtocol.swift`

### Other components

- **Mac user**
- **Apple Metal**
- **Android adbd**

## Connections

- Mac user → Control Panel: manages Android (evidence: `README.md`)
- Control Panel → Daemon client: sends XPC requests (evidence: `README.md`)
- Android app windows → Daemon client: sends XPC input (evidence: `README.md`)
- Menu bar → Runtime daemon: controls VM (evidence: `host/AvoDaemon/MenuBarController.swift`)
- Daemon client → Runtime daemon: calls daemon
- Runtime daemon → VMM engine: spawns engine (evidence: `README.md`)
- Runtime daemon → Android image setup: manages image
- Control Panel → VM configuration: edits settings
- VM configuration → VMM engine: configures VM (evidence: `host/AvoKit/Sources/AvoDaemonCore/VMMEngine.swift`)
- Device profiles → VMM engine: sets boot properties (evidence: `host/AvoKit/Sources/AvoKit/DeviceProfile.swift`)
- Data locations → User data paths: uses data paths (evidence: `host/AvoKit/Sources/AvoDaemonCore/StorageLocations.swift`)
- Runtime daemon → Data locations: manages data
- Android app windows → Host protocol: uses messages (evidence: `host/AvoWindowHost/AndroidWindowController.swift`)
- Daemon client → Host protocol: uses messages
- Android app windows → Display view: routes frames (evidence: `host/AvoWindowHost/AndroidWindowController.swift`)
- Display view → Metal renderer: renders frames (evidence: `host/AvoWindowHost/AndroidWindowController.swift`)
- AOSP Cuttlefish VM → Apple Metal: renders via gfxstream (evidence: `README.md`)
- AOSP Cuttlefish VM → Android apps: runs apps (evidence: `README.md`)
- AOSP Cuttlefish VM → Guest displays: provides virtio devices (evidence: `README.md`)
- Guest bridge agent → Guest displays: starts display service (evidence: `guest/bridge-agent/src/com/avodroid/bridge/Bridge.java`)
- Guest bridge agent → Notification bridge: starts notification bridge (evidence: `guest/bridge-agent/src/com/avodroid/bridge/Bridge.java`)
- Guest displays → Android apps: launches on displays (evidence: `guest/bridge-agent/src/com/avodroid/bridge/display/DisplayController.java`)
- AOSP Cuttlefish VM → Android adbd: provides ADB (evidence: `README.md`)
- Runtime daemon → Guest host agent: coordinates guest agent
- Guest host agent → Guest bridge agent: communicates with guest
- Runtime daemon → Screen translation: supports translation
- AOSP Cuttlefish VM → Android apps: serves app displays (evidence: `README.md`)