# zqxwce/vphone-ws architecture

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

- Interactive diagram: https://gitdiagram.com/zqxwce/vphone-ws
- Repository: https://github.com/zqxwce/vphone-ws

## Overview

vPhone Workstation is a native macOS front end for vphone-cli. Users browse and inspect virtual iPhones, check host readiness, create VMs with selected variants and firmware, and manage or launch existing VMs. The graph separates the SwiftUI screens, application wiring, VM lifecycle and host checks, and the command/task infrastructure. Some subsystem links are based on the SOURCE INDEX or README rather than full excerpts; unsampled implementation details are not inferred.

Main entry points: [`Sources/VPhoneWSCore/Store/AppEnvironment.swift`](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Store/AppEnvironment.swift) (Service Wiring), [`Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift`](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift) (CLI Client), [`Sources/vphone-ws/Views/LibraryView.swift`](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/LibraryView.swift) (VM Library), [`Sources/vphone-ws/Views/CreateWizardView.swift`](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/CreateWizardView.swift) (Create Wizard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["macOS Interface"]
  node_app_entry["App Entry<br/>[App.swift]"]
  node_library["VM Library<br/>[LibraryView.swift]"]
  node_create["Create Wizard"]
  node_detail["VM Details<br/>[VMDetailView.swift]"]
  node_settings["VM Settings"]
  node_progress["Task Progress"]
  node_readiness_ui["Readiness Sheet"]
  node_theme["UI Theme<br/>[Theme.swift]"]
end

subgraph group_app["Application Services"]
  node_environment["Service Wiring"]
end

subgraph group_vm["VM Lifecycle"]
  node_store["VM Store<br/>[VMStore.swift]"]
  node_vm_row["VM Row Model<br/>[VMRow.swift]"]
  node_report["VM Report<br/>[VMReport.swift]"]
  node_lifecycle["Launch Coordinator"]
  node_probe["Running State Probe"]
  node_variants["Variant Store<br/>[VariantStore.swift]"]
  node_firmware["Firmware Catalog"]
  node_process_launcher["Process Launcher"]
end

subgraph group_execution["CLI and Tasks"]
  node_client["CLI Client"]
  node_manage["VM Management"]
  node_locator["CLI Locator"]
  node_runner["CLI Runner<br/>[CLIRunner.swift]"]
  node_system_runner["System CLI Runner"]
  node_stream_runner["Streaming Runner"]
  node_tasks["Task Center<br/>[TaskCenter.swift]"]
  node_task_model["Task Model<br/>[TaskModel.swift]"]
  node_stage_parser["Stage Parser<br/>[StageParser.swift]"]
  node_command_builder["Command Builder"]
end

subgraph group_host["Host Readiness"]
  node_host_readiness["Host Checks"]
  node_host_check["Check Result<br/>[HostCheck.swift]"]
end

node_user(("User"))
node_cli_service["vphone-cli"]

node_user -->|"opens"| node_app_entry
node_app_entry -->|"shows"| node_library
node_app_entry -->|"builds services"| node_environment
node_library -->|"refreshes"| node_store
node_library -->|"checks readiness"| node_host_readiness
node_library -->|"launches VMs"| node_lifecycle
node_library -->|"shows selection"| node_detail
node_library -->|"opens wizard"| node_create
node_library -->|"presents checks"| node_readiness_ui
node_library -->|"starts import"| node_tasks
node_detail -->|"manages VMs"| node_client
node_detail -->|"stops VM"| node_lifecycle
node_detail -->|"starts export"| node_tasks
node_detail -->|"builds export args"| node_command_builder
node_detail -->|"presents settings"| node_settings
node_create -->|"fetches catalog"| node_client
node_create -->|"builds create args"| node_command_builder
node_create -->|"starts creation"| node_tasks
node_create -->|"saves variant"| node_variants
node_create -->|"selects pairing"| node_firmware
node_progress -->|"renders progress"| node_task_model
node_readiness_ui -->|"displays checks"| node_host_readiness
node_library -->|"uses styles"| node_theme
node_environment -->|"constructs"| node_store
node_environment -->|"constructs"| node_lifecycle
node_environment -->|"constructs"| node_client
node_environment -->|"constructs"| node_host_readiness
node_environment -->|"constructs"| node_tasks
node_environment -->|"constructs"| node_command_builder
node_environment -->|"constructs"| node_variants
node_environment -->|"locates CLI"| node_locator
node_environment -->|"configures runner"| node_system_runner
node_store -->|"loads VM reports"| node_client
node_store -->|"checks running state"| node_probe
node_store -->|"creates rows"| node_vm_row
node_vm_row -->|"wraps report"| node_report
node_client -->|"executes commands"| node_runner
node_client -->|"decodes reports"| node_report
node_client -->|"decodes catalog"| node_firmware
node_client -->|"invokes"| node_cli_service
node_manage -->|"extends commands"| node_client
node_host_readiness -->|"locates CLI"| node_locator
node_host_readiness -->|"runs host checks"| node_runner
node_host_readiness -->|"returns results"| node_host_check
node_system_runner -->|"implements"| node_runner
node_lifecycle -->|"launches process"| node_process_launcher
node_lifecycle -->|"stops VM"| node_client
node_lifecycle -->|"checks process"| node_probe

click node_app_entry "https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/App.swift"
click node_library "https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/LibraryView.swift"
click node_create "https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/CreateWizardView.swift"
click node_detail "https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/VMDetailView.swift"
click node_settings "https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/SettingsSheet.swift"
click node_progress "https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/TaskProgressViews.swift"
click node_readiness_ui "https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/HostReadinessSheet.swift"
click node_theme "https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Theme.swift"
click node_environment "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Store/AppEnvironment.swift"
click node_store "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Store/VMStore.swift"
click node_vm_row "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Store/VMRow.swift"
click node_report "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Models/VMReport.swift"
click node_lifecycle "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Lifecycle/LaunchCoordinator.swift"
click node_probe "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/State/RunningStateProbe.swift"
click node_variants "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Variant/VariantStore.swift"
click node_client "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift"
click node_manage "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/CLI/VPhoneCLIClient%2BManage.swift"
click node_locator "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/CLI/VPhoneCLILocator.swift"
click node_runner "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Process/CLIRunner.swift"
click node_system_runner "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Process/SystemCLIRunner.swift"
click node_stream_runner "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Process/StreamingRunner.swift"
click node_tasks "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Tasks/TaskCenter.swift"
click node_task_model "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Tasks/TaskModel.swift"
click node_stage_parser "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Tasks/StageParser.swift"
click node_command_builder "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Tasks/VPhoneCommandBuilder.swift"
click node_firmware "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Models/FirmwareCatalog.swift"
click node_host_readiness "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Host/HostReadiness.swift"
click node_host_check "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Host/HostCheck.swift"
click node_process_launcher "https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Process/ProcessLauncher.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_app_entry,node_library,node_create,node_detail,node_settings,node_progress,node_readiness_ui,node_theme,node_user toneBlue
class node_environment toneAmber
class node_store,node_vm_row,node_report,node_lifecycle,node_probe,node_variants,node_firmware,node_process_launcher toneMint
class node_client,node_manage,node_locator,node_runner,node_system_runner,node_stream_runner,node_tasks,node_task_model,node_stage_parser,node_command_builder toneRose
class node_host_readiness,node_host_check,node_cli_service toneIndigo
```

## Components

### macOS Interface

- [App Entry](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/App.swift): `Sources/vphone-ws/App.swift`
- [VM Library](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/LibraryView.swift): `Sources/vphone-ws/Views/LibraryView.swift`
- [Create Wizard](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/CreateWizardView.swift): `Sources/vphone-ws/Views/CreateWizardView.swift`
- [VM Details](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/VMDetailView.swift): `Sources/vphone-ws/Views/VMDetailView.swift`
- [VM Settings](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/SettingsSheet.swift): `Sources/vphone-ws/Views/SettingsSheet.swift`
- [Task Progress](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/TaskProgressViews.swift): `Sources/vphone-ws/Views/TaskProgressViews.swift`
- [Readiness Sheet](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Views/HostReadinessSheet.swift): `Sources/vphone-ws/Views/HostReadinessSheet.swift`
- [UI Theme](https://github.com/zqxwce/vphone-ws/blob/main/Sources/vphone-ws/Theme.swift): `Sources/vphone-ws/Theme.swift`

### Application Services

- [Service Wiring](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Store/AppEnvironment.swift): `Sources/VPhoneWSCore/Store/AppEnvironment.swift`

### VM Lifecycle

- [VM Store](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Store/VMStore.swift): `Sources/VPhoneWSCore/Store/VMStore.swift`
- [VM Row Model](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Store/VMRow.swift): `Sources/VPhoneWSCore/Store/VMRow.swift`
- [VM Report](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Models/VMReport.swift): `Sources/VPhoneWSCore/Models/VMReport.swift`
- [Launch Coordinator](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Lifecycle/LaunchCoordinator.swift): `Sources/VPhoneWSCore/Lifecycle/LaunchCoordinator.swift`
- [Running State Probe](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/State/RunningStateProbe.swift): `Sources/VPhoneWSCore/State/RunningStateProbe.swift`
- [Variant Store](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Variant/VariantStore.swift): `Sources/VPhoneWSCore/Variant/VariantStore.swift`
- [Firmware Catalog](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Models/FirmwareCatalog.swift): `Sources/VPhoneWSCore/Models/FirmwareCatalog.swift`
- [Process Launcher](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Process/ProcessLauncher.swift): `Sources/VPhoneWSCore/Process/ProcessLauncher.swift`

### CLI and Tasks

- [CLI Client](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift): `Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift`
- [VM Management](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/CLI/VPhoneCLIClient%2BManage.swift): `Sources/VPhoneWSCore/CLI/VPhoneCLIClient+Manage.swift`
- [CLI Locator](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/CLI/VPhoneCLILocator.swift): `Sources/VPhoneWSCore/CLI/VPhoneCLILocator.swift`
- [CLI Runner](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Process/CLIRunner.swift): `Sources/VPhoneWSCore/Process/CLIRunner.swift`
- [System CLI Runner](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Process/SystemCLIRunner.swift): `Sources/VPhoneWSCore/Process/SystemCLIRunner.swift`
- [Streaming Runner](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Process/StreamingRunner.swift): `Sources/VPhoneWSCore/Process/StreamingRunner.swift`
- [Task Center](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Tasks/TaskCenter.swift): `Sources/VPhoneWSCore/Tasks/TaskCenter.swift`
- [Task Model](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Tasks/TaskModel.swift): `Sources/VPhoneWSCore/Tasks/TaskModel.swift`
- [Stage Parser](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Tasks/StageParser.swift): `Sources/VPhoneWSCore/Tasks/StageParser.swift`
- [Command Builder](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Tasks/VPhoneCommandBuilder.swift): `Sources/VPhoneWSCore/Tasks/VPhoneCommandBuilder.swift`

### Host Readiness

- [Host Checks](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Host/HostReadiness.swift): `Sources/VPhoneWSCore/Host/HostReadiness.swift`
- [Check Result](https://github.com/zqxwce/vphone-ws/blob/main/Sources/VPhoneWSCore/Host/HostCheck.swift): `Sources/VPhoneWSCore/Host/HostCheck.swift`

### Other components

- **User**
- **vphone-cli**

## Connections

- User → App Entry: opens (evidence: `Sources/vphone-ws/App.swift`)
- App Entry → VM Library: shows (evidence: `Sources/vphone-ws/App.swift`)
- App Entry → Service Wiring: builds services (evidence: `Sources/vphone-ws/App.swift`)
- VM Library → VM Store: refreshes (evidence: `Sources/vphone-ws/Views/LibraryView.swift`)
- VM Library → Host Checks: checks readiness (evidence: `Sources/vphone-ws/Views/LibraryView.swift`)
- VM Library → Launch Coordinator: launches VMs (evidence: `Sources/vphone-ws/Views/LibraryView.swift`)
- VM Library → VM Details: shows selection (evidence: `Sources/vphone-ws/Views/LibraryView.swift`)
- VM Library → Create Wizard: opens wizard (evidence: `Sources/vphone-ws/Views/LibraryView.swift`)
- VM Library → Readiness Sheet: presents checks (evidence: `Sources/vphone-ws/Views/LibraryView.swift`)
- VM Library → Task Center: starts import (evidence: `Sources/vphone-ws/Views/LibraryView.swift`)
- VM Details → CLI Client: manages VMs (evidence: `Sources/vphone-ws/Views/VMDetailView.swift`)
- VM Details → Launch Coordinator: stops VM (evidence: `Sources/vphone-ws/Views/VMDetailView.swift`)
- VM Details → Task Center: starts export (evidence: `Sources/vphone-ws/Views/VMDetailView.swift`)
- VM Details → Command Builder: builds export args (evidence: `Sources/vphone-ws/Views/VMDetailView.swift`)
- VM Details → VM Settings: presents settings (evidence: `Sources/vphone-ws/Views/VMDetailView.swift`)
- Create Wizard → CLI Client: fetches catalog (evidence: `Sources/vphone-ws/Views/CreateWizardView.swift`)
- Create Wizard → Command Builder: builds create args (evidence: `Sources/vphone-ws/Views/CreateWizardView.swift`)
- Create Wizard → Task Center: starts creation (evidence: `Sources/vphone-ws/Views/CreateWizardView.swift`)
- Create Wizard → Variant Store: saves variant (evidence: `Sources/vphone-ws/Views/CreateWizardView.swift`)
- Create Wizard → Firmware Catalog: selects pairing (evidence: `Sources/vphone-ws/Views/CreateWizardView.swift`)
- Task Progress → Task Model: renders progress (evidence: `Sources/vphone-ws/Views/TaskProgressViews.swift`)
- Readiness Sheet → Host Checks: displays checks (evidence: `Sources/vphone-ws/Views/HostReadinessSheet.swift`)
- VM Library → UI Theme: uses styles (evidence: `Sources/vphone-ws/Views/LibraryView.swift`)
- Service Wiring → VM Store: constructs (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- Service Wiring → Launch Coordinator: constructs (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- Service Wiring → CLI Client: constructs (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- Service Wiring → Host Checks: constructs (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- Service Wiring → Task Center: constructs (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- Service Wiring → Command Builder: constructs (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- Service Wiring → Variant Store: constructs (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- Service Wiring → CLI Locator: locates CLI (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- Service Wiring → System CLI Runner: configures runner (evidence: `Sources/VPhoneWSCore/Store/AppEnvironment.swift`)
- VM Store → CLI Client: loads VM reports (evidence: `Sources/VPhoneWSCore/Store/VMStore.swift`)
- VM Store → Running State Probe: checks running state (evidence: `Sources/VPhoneWSCore/Store/VMStore.swift`)
- VM Store → VM Row Model: creates rows (evidence: `Sources/VPhoneWSCore/Store/VMStore.swift`)
- VM Row Model → VM Report: wraps report (evidence: `Sources/VPhoneWSCore/Store/VMRow.swift`)
- CLI Client → CLI Runner: executes commands (evidence: `Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift`)
- CLI Client → VM Report: decodes reports (evidence: `Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift`)
- CLI Client → Firmware Catalog: decodes catalog (evidence: `Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift`)
- CLI Client → vphone-cli: invokes (evidence: `Sources/VPhoneWSCore/CLI/VPhoneCLIClient.swift`)
- VM Management → CLI Client: extends commands (evidence: `Sources/VPhoneWSCore/CLI/VPhoneCLIClient+Manage.swift`)
- Host Checks → CLI Locator: locates CLI (evidence: `Sources/VPhoneWSCore/Host/HostReadiness.swift`)
- Host Checks → CLI Runner: runs host checks (evidence: `Sources/VPhoneWSCore/Host/HostReadiness.swift`)
- Host Checks → Check Result: returns results (evidence: `Sources/VPhoneWSCore/Host/HostReadiness.swift`)
- System CLI Runner → CLI Runner: implements (evidence: `Sources/VPhoneWSCore/Process/SystemCLIRunner.swift`)
- Launch Coordinator → Process Launcher: launches process (evidence: `Sources/VPhoneWSCore/Lifecycle/LaunchCoordinator.swift`)
- Launch Coordinator → CLI Client: stops VM (evidence: `Sources/VPhoneWSCore/Lifecycle/LaunchCoordinator.swift`)
- Launch Coordinator → Running State Probe: checks process (evidence: `Sources/VPhoneWSCore/Lifecycle/LaunchCoordinator.swift`)
