# insidegui/virtualbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/insidegui/virtualbuddy
- Repository: https://github.com/insidegui/virtualbuddy

## Overview

VirtualBuddy is a macOS virtualization application. The principal workflow is: a user selects or creates a VM, the application stores it in the VM library, launches a session, configures virtualization, and boots the guest OS. Installation branches through Apple restore-image catalogs or local/custom images, while configuration supports hardware, storage, networking, sharing, and saved states. The sampled code confirms library/session orchestration, catalog loading, storage modeling, saved-state lookup, and guest-folder mounting; several backend links are inferred only from documented capabilities and tree paths.

Main entry points: [`VirtualUI/Source/Installer/VMInstallationWizard.swift`](https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/Installer/VMInstallationWizard.swift) (Installation Wizard), [`VirtualUI/Source/Session/VirtualMachineSessionUIManager.swift`](https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/Session/VirtualMachineSessionUIManager.swift) (Session Manager), [`VirtualCore/Source/Virtualization/VMController.swift`](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMController.swift) (VM Controller), [`VirtualCore/Source/Virtualization/Helpers/VirtualMachineConfigurationHelper.swift`](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/Helpers/VirtualMachineConfigurationHelper.swift) (VM Configurator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Application UI"]
  node_virtualbuddy_app["VirtualBuddy App"]
  node_session_ui["Session Manager"]
  node_config_ui["Configuration UI"]
end

subgraph group_library["VM Management"]
  node_library_controller["VM Library"]
  node_vm_model["VM Model"]
  node_storage_model["Storage Model"]
  node_saved_states["Saved States"]
end

subgraph group_install["Installation"]
  node_installer["Installation Wizard"]
  node_catalog_controller["Restore Catalog"]
  node_catalog_api["Restore API<br/>[VBAPIClient.swift]"]
  node_download_backend["Download Backend"]
  node_restore_backend["Restore Backend"]
end

subgraph group_runtime["Virtualization Runtime"]
  node_vm_controller["VM Controller<br/>[VMController.swift]"]
  node_vm_instance["VM Instance<br/>[VMInstance.swift]"]
  node_vm_config_helper["VM Configurator"]
  node_networking["Network Devices"]
end

subgraph group_guest["Guest Integration"]
  node_guest_support["Guest Support"]
  node_guest_connection["Guest Connection"]
  node_guest_folders["Shared Folder Mount"]
end

node_user(("User"))
node_apple_servers{{"Apple Restore Servers"}}
node_host_filesystem[("Host Filesystem")]
node_guest_os(("Guest OS"))

node_user -->|"uses"| node_virtualbuddy_app
node_virtualbuddy_app -->|"opens sessions"| node_session_ui
node_session_ui -->|"loads VMs"| node_library_controller
node_session_ui -->|"launches VM"| node_vm_controller
node_vm_controller -->|"controls runtime"| node_vm_instance
node_vm_controller -->|"builds configuration"| node_vm_config_helper
node_vm_config_helper -->|"resolves disks"| node_storage_model
node_vm_config_helper -->|"configures network"| node_networking
node_config_ui -->|"updates configuration"| node_vm_model
node_storage_model -->|"resolves images"| node_host_filesystem
node_library_controller -->|"creates states"| node_saved_states
node_saved_states -->|"finds VM"| node_vm_model
node_user -->|"starts install"| node_installer
node_installer -->|"selects image"| node_catalog_controller
node_catalog_controller -->|"fetches catalog"| node_catalog_api
node_catalog_api -->|"requests images"| node_apple_servers
node_installer -->|"downloads image"| node_download_backend
node_installer -->|"installs system"| node_restore_backend
node_restore_backend -->|"creates VM"| node_vm_model
node_vm_instance -->|"communicates guest"| node_guest_connection
node_guest_support -->|"provides guest services"| node_guest_connection
node_guest_os -->|"runs mount"| node_guest_folders
node_guest_folders -->|"mounts shared folders"| node_host_filesystem

click node_virtualbuddy_app "https://github.com/insidegui/virtualbuddy/blob/main/VirtualBuddy/Bootstrap/VirtualBuddyApp.swift"
click node_session_ui "https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/Session/VirtualMachineSessionUIManager.swift"
click node_library_controller "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMLibraryController.swift"
click node_vm_model "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Models/VBVirtualMachine.swift"
click node_config_ui "https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/VM%20Configuration/VMConfigurationViewModel.swift"
click node_storage_model "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Models/VBStorageDeviceContainer.swift"
click node_saved_states "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Models/SavedState/VMLibraryController%2BSavedState.swift"
click node_installer "https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/Installer/VMInstallationWizard.swift"
click node_catalog_controller "https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/Installer/Steps/Restore%20Image%20Selection/RestoreImageSelectionController.swift"
click node_catalog_api "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Restore%20Images/VBAPIClient.swift"
click node_download_backend "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Restore/Download/URLSessionDownloadBackend.swift"
click node_restore_backend "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Restore/Installation/VirtualizationRestoreBackend.swift"
click node_vm_controller "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMController.swift"
click node_vm_instance "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMInstance.swift"
click node_vm_config_helper "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/Helpers/VirtualMachineConfigurationHelper.swift"
click node_networking "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMNetworkAttachmentHelper.swift"
click node_guest_support "https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/GuestSupport/GuestAppSupport.swift"
click node_guest_connection "https://github.com/insidegui/virtualbuddy/blob/main/VirtualWormhole/Source/GuestConnection.swift"
click node_guest_folders "https://github.com/insidegui/virtualbuddy/blob/main/VirtualBuddyGuest/Dashboard/GuestSharedFoldersManager.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_virtualbuddy_app,node_session_ui,node_config_ui,node_user toneBlue
class node_library_controller,node_vm_model,node_storage_model,node_saved_states,node_host_filesystem toneAmber
class node_installer,node_catalog_controller,node_catalog_api,node_download_backend,node_restore_backend,node_apple_servers toneMint
class node_vm_controller,node_vm_instance,node_vm_config_helper,node_networking toneRose
class node_guest_support,node_guest_connection,node_guest_folders,node_guest_os toneIndigo
```

## Components

### Application UI

- [VirtualBuddy App](https://github.com/insidegui/virtualbuddy/blob/main/VirtualBuddy/Bootstrap/VirtualBuddyApp.swift): `VirtualBuddy/Bootstrap/VirtualBuddyApp.swift`
- [Session Manager](https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/Session/VirtualMachineSessionUIManager.swift): `VirtualUI/Source/Session/VirtualMachineSessionUIManager.swift`
- [Configuration UI](https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/VM%20Configuration/VMConfigurationViewModel.swift): `VirtualUI/Source/VM Configuration/VMConfigurationViewModel.swift`

### VM Management

- [VM Library](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMLibraryController.swift): `VirtualCore/Source/Virtualization/VMLibraryController.swift`
- [VM Model](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Models/VBVirtualMachine.swift): `VirtualCore/Source/Models/VBVirtualMachine.swift`
- [Storage Model](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Models/VBStorageDeviceContainer.swift): `VirtualCore/Source/Models/VBStorageDeviceContainer.swift`
- [Saved States](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Models/SavedState/VMLibraryController%2BSavedState.swift): `VirtualCore/Source/Models/SavedState/VMLibraryController+SavedState.swift`

### Installation

- [Installation Wizard](https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/Installer/VMInstallationWizard.swift): `VirtualUI/Source/Installer/VMInstallationWizard.swift`
- [Restore Catalog](https://github.com/insidegui/virtualbuddy/blob/main/VirtualUI/Source/Installer/Steps/Restore%20Image%20Selection/RestoreImageSelectionController.swift): `VirtualUI/Source/Installer/Steps/Restore Image Selection/RestoreImageSelectionController.swift`
- [Restore API](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Restore%20Images/VBAPIClient.swift): `VirtualCore/Source/Restore Images/VBAPIClient.swift`
- [Download Backend](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Restore/Download/URLSessionDownloadBackend.swift): `VirtualCore/Source/Restore/Download/URLSessionDownloadBackend.swift`
- [Restore Backend](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Restore/Installation/VirtualizationRestoreBackend.swift): `VirtualCore/Source/Restore/Installation/VirtualizationRestoreBackend.swift`

### Virtualization Runtime

- [VM Controller](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMController.swift): `VirtualCore/Source/Virtualization/VMController.swift`
- [VM Instance](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMInstance.swift): `VirtualCore/Source/Virtualization/VMInstance.swift`
- [VM Configurator](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/Helpers/VirtualMachineConfigurationHelper.swift): `VirtualCore/Source/Virtualization/Helpers/VirtualMachineConfigurationHelper.swift`
- [Network Devices](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/Virtualization/VMNetworkAttachmentHelper.swift): `VirtualCore/Source/Virtualization/VMNetworkAttachmentHelper.swift`

### Guest Integration

- [Guest Support](https://github.com/insidegui/virtualbuddy/blob/main/VirtualCore/Source/GuestSupport/GuestAppSupport.swift): `VirtualCore/Source/GuestSupport/GuestAppSupport.swift`
- [Guest Connection](https://github.com/insidegui/virtualbuddy/blob/main/VirtualWormhole/Source/GuestConnection.swift): `VirtualWormhole/Source/GuestConnection.swift`
- [Shared Folder Mount](https://github.com/insidegui/virtualbuddy/blob/main/VirtualBuddyGuest/Dashboard/GuestSharedFoldersManager.swift): `VirtualBuddyGuest/Dashboard/GuestSharedFoldersManager.swift`

### Other components

- **User**
- **Apple Restore Servers**
- **Host Filesystem**
- **Guest OS**

## Connections

- User → VirtualBuddy App: uses
- VirtualBuddy App → Session Manager: opens sessions
- Session Manager → VM Library: loads VMs
- Session Manager → VM Controller: launches VM
- VM Controller → VM Instance: controls runtime
- VM Controller → VM Configurator: builds configuration
- VM Configurator → Storage Model: resolves disks
- VM Configurator → Network Devices: configures network
- Configuration UI → VM Model: updates configuration
- Storage Model → Host Filesystem: resolves images
- VM Library → Saved States: creates states
- Saved States → VM Model: finds VM
- User → Installation Wizard: starts install
- Installation Wizard → Restore Catalog: selects image
- Restore Catalog → Restore API: fetches catalog
- Restore API → Apple Restore Servers: requests images
- Installation Wizard → Download Backend: downloads image
- Installation Wizard → Restore Backend: installs system
- Restore Backend → VM Model: creates VM
- VM Instance → Guest Connection: communicates guest
- Guest Support → Guest Connection: provides guest services
- Guest OS → Shared Folder Mount: runs mount
- Shared Folder Mount → Host Filesystem: mounts shared folders
