# tibixdev/winboat architecture

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

- Interactive diagram: https://gitdiagram.com/tibixdev/winboat
- Repository: https://github.com/tibixdev/winboat

## Overview

1. **Overall shape**: WinBoat is a desktop application, not a service or web app. The runtime is split between an **Electron shell** on the Linux host, a **Vue/TypeScript renderer UI**, a **Go-based Windows guest server**, and the **container runtime** that hosts the Windows VM.

2. **Host application boundary**: `src/main/main.ts` is the Electron main-process entry point. Its role is to create the app window, load the renderer bundle, and act as the native desktop wrapper around the rest of the system.

3. **Renderer/UI layer**: `src/renderer` contains the full user-facing app: setup, home/dashboard, apps, configuration, migration, and about views. The UI uses Vue components plus shared styling/assets, with a small utility layer for events, logging, port handling, and window/desktop behaviors.

4. **Application orchestration in the renderer**: Most product logic lives in `src/renderer/lib`. This layer handles config, install/setup flows, migration, launching, and domain-specific helpers. It is the bridge between UI actions and the underlying host/guest infrastructure.

5. **Container-runtime abstraction**: WinBoat supports **Docker and Podman** through a shared container layer in `src/renderer/lib/containers`, with runtime-specific implementations for each. This is a key architectural boundary: the app does not directly manage a bare VM; it manages a Windows VM running inside a container.

6. **VM/control plane**: `src/renderer/lib/qmp.ts` indicates QEMU/QMP-based control of the VM lifecycle. The host app uses this channel to coordinate startup, status, and low-level VM operations separate from the UI and separate from the guest OS.

7. **Windows guest agent**: The `guest_server/` directory is a separate Go project built for the Windows VM. It is installed and run as a Windows service using the provided scripts/tools, and it exposes guest-side capabilities such as system data, app management, icon retrieval, time sync, update-related actions, and secure key handling.

8. **Remote desktop and app presentation**: WinBoat uses **FreeRDP** and Windows **RemoteApp** to render Windows applications as native-looking Linux windows. The renderer’s container/app modules and helpers are responsible for discovering apps, launching them, and connecting the UI to the RDP session.

9. **Device and file integration**: The repository includes explicit support for USB handling (`usbmanager.ts` and `data/usb.ids`) and filesystem integration via the host/guest bridge. This is part of the “make Windows feel native” layer rather than a separate subsystem.

10. **Configuration, install, and migration flow**: First-run setup and subsequent upgrades are handled by dedicated flows in `SetupUI`, `Migration`, and related libraries. Configuration is a central piece of state that determines container runtime, VM resources, app exposure, and integration behavior.

11. **Build and packaging boundary**: The project is built with **Bun/TypeScript** for the Electron app and **Go** for the guest server. `vite.config.ts`, `electron-builder.json`, `scripts/build.ts`, and the GitHub release workflow define packaging into AppImage/deb/rpm/unpacked formats, while `build-guest-server.sh` produces the guest-side binary.

12. **External dependencies that shape the architecture**: The repo depends on Linux virtualization/container infrastructure (**Docker or Podman**, **KVM**, optionally `iptables`/`nftables`) and on a working **FreeRDP 3.x** install. These are not optional implementation details; they are core parts of the system boundary WinBoat sits on top of.

Main entry points: [`src/renderer/lib`](https://github.com/tibixdev/winboat/tree/main/src/renderer/lib) (Orchestration), [`src/renderer/App.vue`](https://github.com/tibixdev/winboat/blob/main/src/renderer/App.vue) (Renderer app), [`guest_server/main.go`](https://github.com/tibixdev/winboat/blob/main/guest_server/main.go) (Guest server), [`src/renderer/lib/containers`](https://github.com/tibixdev/winboat/tree/main/src/renderer/lib/containers) (Container layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Linux host app"]
  node_electron_main["Electron main<br/>host entry<br/>[main.ts]"]
  node_renderer_app["Renderer app<br/>Vue UI<br/>[App.vue]"]
  node_ui_views["App views<br/>screens"]
  node_ui_components["UI components<br/>widgets"]
  node_ui_utils["UI utilities<br/>helpers"]
  node_renderer_lib["Orchestration<br/>product logic"]
  node_winboat_core["WinBoat core<br/>state/coordination<br/>[winboat.ts]"]
  node_usb_integration["USB manager<br/>device bridge<br/>[usbmanager.ts]"]
  node_config_flow["Config flow<br/>setup state<br/>[config.ts]"]
  node_migration_flow["Migration flow<br/>upgrade path<br/>[migrate.ts]"]
  node_install_flow["Install flow<br/>bootstrap<br/>[install.ts]"]
end

subgraph group_guest["Windows guest"]
  node_guest_server["Guest server<br/>Go service<br/>[main.go]"]
  node_guest_scripts["Guest scripts<br/>service tools"]
  node_securekey["Secure key<br/>crypto helper<br/>[securekey.go]"]
  node_rdp_apps["RemoteApp bridge<br/>app presentation<br/>[RDPApps.reg]"]
end

subgraph group_runtime["Container/VM runtime"]
  node_container_iface["Container layer<br/>abstraction"]
  node_docker_impl["Docker backend<br/>runtime impl<br/>[docker.ts]"]
  node_podman_impl["Podman backend<br/>runtime impl<br/>[podman.ts]"]
  node_qmp_control["QMP control<br/>vm control<br/>[qmp.ts]"]
end

subgraph group_build["Build & packaging"]
  node_build_tooling["Build tooling<br/>packaging<br/>[build.ts]"]
  node_guest_build["Guest build<br/>artifact build"]
  node_release_pipeline["Release pipeline<br/>ci workflow<br/>[release.yml]"]
end

node_electron_main -->|"loads UI"| node_renderer_app
node_renderer_app -->|"routes to"| node_ui_views
node_renderer_app -->|"renders"| node_ui_components
node_renderer_app -->|"uses"| node_ui_utils
node_ui_views -->|"drives"| node_renderer_lib
node_renderer_lib -->|"reads/writes"| node_config_flow
node_renderer_lib -->|"bootstraps"| node_install_flow
node_renderer_lib -->|"upgrades"| node_migration_flow
node_renderer_lib -->|"coordinates"| node_winboat_core
node_winboat_core -->|"uses"| node_container_iface
node_container_iface -->|"backend"| node_docker_impl
node_container_iface -->|"backend"| node_podman_impl
node_winboat_core -->|"controls VM"| node_qmp_control
node_container_iface -->|"hosts"| node_guest_server
node_guest_server -->|"invokes"| node_guest_scripts
node_guest_server -->|"auth"| node_securekey
node_guest_server -->|"publishes"| node_rdp_apps
node_renderer_lib -->|"integrates"| node_usb_integration
node_renderer_lib -->|"uses"| node_ui_utils
node_build_tooling -->|"packages"| node_electron_main
node_build_tooling -->|"bundles"| node_renderer_app
node_guest_build -->|"builds"| node_guest_server
node_release_pipeline -->|"automates"| node_build_tooling
node_release_pipeline -->|"includes"| node_guest_build

click node_electron_main "https://github.com/tibixdev/winboat/blob/main/src/main/main.ts"
click node_renderer_app "https://github.com/tibixdev/winboat/blob/main/src/renderer/App.vue"
click node_ui_views "https://github.com/tibixdev/winboat/tree/main/src/renderer/views"
click node_ui_components "https://github.com/tibixdev/winboat/tree/main/src/renderer/components"
click node_ui_utils "https://github.com/tibixdev/winboat/tree/main/src/renderer/utils"
click node_renderer_lib "https://github.com/tibixdev/winboat/tree/main/src/renderer/lib"
click node_container_iface "https://github.com/tibixdev/winboat/tree/main/src/renderer/lib/containers"
click node_docker_impl "https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/containers/docker.ts"
click node_podman_impl "https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/containers/podman.ts"
click node_qmp_control "https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/qmp.ts"
click node_winboat_core "https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/winboat.ts"
click node_guest_server "https://github.com/tibixdev/winboat/blob/main/guest_server/main.go"
click node_guest_scripts "https://github.com/tibixdev/winboat/tree/main/guest_server/scripts"
click node_securekey "https://github.com/tibixdev/winboat/blob/main/guest_server/securekey.go"
click node_rdp_apps "https://github.com/tibixdev/winboat/blob/main/guest_server/RDPApps.reg"
click node_usb_integration "https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/usbmanager.ts"
click node_config_flow "https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/config.ts"
click node_migration_flow "https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/migrate.ts"
click node_install_flow "https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/install.ts"
click node_build_tooling "https://github.com/tibixdev/winboat/blob/main/scripts/build.ts"
click node_guest_build "https://github.com/tibixdev/winboat/blob/main/build-guest-server.sh"
click node_release_pipeline "https://github.com/tibixdev/winboat/blob/main/.github/workflows/release.yml"

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_electron_main,node_renderer_app,node_ui_views,node_ui_components,node_ui_utils,node_renderer_lib,node_winboat_core,node_usb_integration,node_config_flow,node_migration_flow,node_install_flow toneBlue
class node_guest_server,node_guest_scripts,node_securekey,node_rdp_apps toneAmber
class node_container_iface,node_docker_impl,node_podman_impl,node_qmp_control toneMint
class node_build_tooling,node_guest_build,node_release_pipeline toneRose
```

## Components

### Linux host app

Electron shell and renderer running on the Linux desktop.

- [Electron main](https://github.com/tibixdev/winboat/blob/main/src/main/main.ts): host entry · Creates the desktop window and loads the renderer bundle. · `src/main/main.ts`
- [Renderer app](https://github.com/tibixdev/winboat/blob/main/src/renderer/App.vue): Vue UI · Top-level Vue application and route composition for the desktop UI. · `src/renderer/App.vue`
- [App views](https://github.com/tibixdev/winboat/tree/main/src/renderer/views): screens · Setup, home, apps, config, migration, and about screens. · `src/renderer/views`
- [UI components](https://github.com/tibixdev/winboat/tree/main/src/renderer/components): widgets · Reusable interface components and menus used across the app. · `src/renderer/components`
- [UI utilities](https://github.com/tibixdev/winboat/tree/main/src/renderer/utils): helpers · Shared event, logging, port, RDP, and browser/window helpers. · `src/renderer/utils`
- [Orchestration](https://github.com/tibixdev/winboat/tree/main/src/renderer/lib): product logic · Configuration, setup, install, migration, and launch coordination. · `src/renderer/lib`
- [WinBoat core](https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/winboat.ts): state/coordination · Central runtime state and high-level app coordination. · `src/renderer/lib/winboat.ts`
- [USB manager](https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/usbmanager.ts): device bridge · USB device handling and host/guest passthrough integration. · `src/renderer/lib/usbmanager.ts`
- [Config flow](https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/config.ts): setup state · Central configuration model used by setup, runtime, and integration features. · `src/renderer/lib/config.ts`
- [Migration flow](https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/migrate.ts): upgrade path · Upgrade and state migration logic for existing installations. · `src/renderer/lib/migrate.ts`
- [Install flow](https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/install.ts): bootstrap · Initial provisioning and environment preparation logic. · `src/renderer/lib/install.ts`

### Windows guest

Go service and scripts that run inside the Windows VM.

- [Guest server](https://github.com/tibixdev/winboat/blob/main/guest_server/main.go): Go service · Windows-side agent exposing guest capabilities and integration endpoints. · `guest_server/main.go`
- [Guest scripts](https://github.com/tibixdev/winboat/tree/main/guest_server/scripts): service tools · PowerShell and batch scripts for apps, icons, time sync, and updates. · `guest_server/scripts`
- [Secure key](https://github.com/tibixdev/winboat/blob/main/guest_server/securekey.go): crypto helper · Guest-side secure key and auth helper logic. · `guest_server/securekey.go`
- [RemoteApp bridge](https://github.com/tibixdev/winboat/blob/main/guest_server/RDPApps.reg): app presentation · Windows app discovery and RemoteApp registration for FreeRDP presentation. · `guest_server/RDPApps.reg`

### Container/VM runtime

Container and VM control boundaries used to host the guest.

- [Container layer](https://github.com/tibixdev/winboat/tree/main/src/renderer/lib/containers): abstraction · Shared container-runtime interface for managing the Windows VM host. · `src/renderer/lib/containers`
- [Docker backend](https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/containers/docker.ts): runtime impl · Docker-specific container integration. · `src/renderer/lib/containers/docker.ts`
- [Podman backend](https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/containers/podman.ts): runtime impl · Podman-specific container integration. · `src/renderer/lib/containers/podman.ts`
- [QMP control](https://github.com/tibixdev/winboat/blob/main/src/renderer/lib/qmp.ts): vm control · QEMU/QMP channel for VM lifecycle and low-level host control. · `src/renderer/lib/qmp.ts`

### Build & packaging

Tooling and release pipeline for the desktop app and guest server.

- [Build tooling](https://github.com/tibixdev/winboat/blob/main/scripts/build.ts): packaging · Bun/TypeScript build pipeline and app packaging configuration. · `scripts/build.ts`
- [Guest build](https://github.com/tibixdev/winboat/blob/main/build-guest-server.sh): artifact build · Build script for producing the Windows guest-server binary. · `build-guest-server.sh`
- [Release pipeline](https://github.com/tibixdev/winboat/blob/main/.github/workflows/release.yml): ci workflow · GitHub Actions release automation for packaged desktop artifacts. · `.github/workflows/release.yml`

## Connections

- Electron main → Renderer app: loads UI · Electron shell creates the desktop window and loads the renderer bundle.
- Renderer app → App views: routes to · Top-level app composes the product screens.
- Renderer app → UI components: renders · Views are built from reusable interface components.
- Renderer app → UI utilities: uses · The UI depends on shared helper utilities.
- App views → Orchestration: drives · User actions in setup, home, config, and migration flow into orchestration logic.
- Orchestration → Config flow: reads/writes · Configuration is the central state for runtime behavior and integrations.
- Orchestration → Install flow: bootstraps · Initial setup provisions the application environment.
- Orchestration → Migration flow: upgrades · Migration handles changes between installed versions.
- Orchestration → WinBoat core: coordinates · Product logic delegates shared runtime orchestration to the core state layer.
- WinBoat core → Container layer: uses · Core runtime control is built on the container abstraction.
- Container layer → Docker backend: backend · Docker is one supported container runtime.
- Container layer → Podman backend: backend · Podman is the other supported container runtime.
- WinBoat core → QMP control: controls VM · QMP provides lifecycle and low-level VM control.
- Container layer → Guest server: hosts · The container/VM environment runs the Windows guest agent.
- Guest server → Guest scripts: invokes · Guest-side capabilities are exposed through service scripts and tools.
- Guest server → Secure key: auth · Secure key logic protects guest-side interactions.
- Guest server → RemoteApp bridge: publishes · Guest app registration feeds RemoteApp presentation.
- Orchestration → USB manager: integrates · USB passthrough is managed as part of the host/guest bridge.
- Orchestration → UI utilities: uses · Orchestration reuses utility helpers for ports, events, and process handling.
- Build tooling → Electron main: packages · Build tooling bundles the Electron desktop app.
- Build tooling → Renderer app: bundles · Renderer code is compiled and packaged as part of the desktop app.
- Guest build → Guest server: builds · Shell build script produces the guest-server binary.
- Release pipeline → Build tooling: automates · CI release workflow drives app packaging and publishing.
- Release pipeline → Guest build: includes · Release automation includes the guest-server artifact.
