GitHub

Architecture

Architecture

Component responsibilities and the current system boundary.

Wave VM is a Tauri 2 desktop application. The Rust backend is authoritative for host detection, VM validation, persistence, disk creation, and process lifecycle. The frontend is static HTML, CSS, and JavaScript served by Tauri; it renders structured results and invokes a small set of commands.

Current components

src/                     Vanilla HTML, CSS, and ES modules
  app.js                 Bootstrap, router wiring, page lifecycle
  components/            Persistent shell and reusable UI
  pages/                 Dashboard, machines, storage, media, settings
  services/              Tauri command wrappers and preferences
  state/                 Shared host and machine state
  vendor/novnc/          Bundled noVNC client and licenses
src-tauri/src/
  commands/              Narrow Tauri command handlers
  config/                Versioned configuration, migration, atomic persistence
  host/                  Host diagnostics, memory/storage, KVM probe
  qemu/                  Executable discovery, safe version probing
  qmp/                   Minimal QMP client over a local Unix socket
  vm/                    VM models, validation, disk creation, process lifecycle
  error.rs               Shared serialized application errors
  state.rs               Application state and tracked QEMU processes

Backend responsibilities

  • Resolve the application data directory and initialize configuration.
  • Collect host diagnostics and report warnings.
  • Discover QEMU and qemu-img executables and probe their versions.
  • Verify Linux KVM by opening the device and issuing an ioctl.
  • Validate and persist machine definitions.
  • Create QCOW2 disks without overwriting existing files.
  • Launch, track, and stop QEMU processes, with QMP control and bounded termination fallbacks.
  • Configure a loopback VNC WebSocket listener and expose a per-run console session.
  • Serialize errors into a stable shape for the frontend.

Frontend responsibilities

  • Render loading, error, empty, host-readiness, machine, storage, and console states.
  • Invoke the registered commands through Tauri's command bridge.
  • Present lifecycle state and backend errors without inventing state.
  • Connect the bundled noVNC client to the loopback console session.

This is the current architecture

There is no media manager, networking module, snapshot layer, or machine editing workflow yet. The architecture documentation describes what exists, not a completed target design.

Explore the details