# winapps-org/winapps architecture

> Architecture diagram of the GitHub repository winapps-org/winapps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/winapps-org/winapps
- Repository: https://github.com/winapps-org/winapps

## Overview

##### Project Type and Purpose
- WinApps is an open-source integration tool that lets users run Windows applications on a GNU/Linux host by provisioning a Windows VM/container (via Docker, Podman or libvirt) and using FreeRDP to render individual Windows apps seamlessly alongside native Linux applications.

##### File Structure Analysis
- Top-level:
- README.md, LICENSE.md, CONTRIBUTING.md, docs/ — project documentation.
- bin/winapps — the main CLI entry point.
- setup.sh and install/ — installer scripts for bootstrapping the environment.
- docs/docker.md, docs/libvirt.md — guides for configuring Docker/Podman and libvirt backends.
- compose.yaml — Docker Compose definition for spinning up the VM container.
- default.nix, flake.nix, flake.lock, packages/ — Nix integration and packaging metadata.
- oem/ — optional OEM scripts and registry tweaks (e.g., RDPApps.reg).

##### Key README Insights
- Underlying mechanism:
1. Provision Windows VM/container with KVM hypervisor.
2. Query installed Windows apps via a scanning script.
3. Generate Linux-side shortcuts (`.desktop` files) and MIME associations.
4. Launch selected Windows apps over RDP using FreeRDP.
- Supports backends: Docker, Podman, libvirt, manual.
- Configuration: `~/.config/winapps/winapps.conf`.

##### Main Components
a. Host Linux Environment
- Configuration store (`~/.config/winapps/`).
- CLI tools: `bin/winapps`, `install/`, `setup.sh`.
- Desktop integration: `.desktop` files, MIME database, Nautilus extension.
- Optional tray UI: WinApps-Launcher (separate package under packages/winapps-launcher).
b. Virtualization Backend Abstraction
- Docker/Podman (`compose.yaml`, Dockerfiles).
- libvirt (`docs/libvirt.md`, oem/ scripts).
- Manual mode fallback.
c. Windows VM/Container
- Windows guest OS running RDP server.
- Shared mount of host home (`\\tsclient\home`).
d. FreeRDP Client
- Invoked by WinApps CLI (`xfreerdp` or specified FREERDP_COMMAND).
- Streams individual application windows back to the host X11/Wayland session.
e. Application Definition Modules (`apps/…`)
- Template variables for `.desktop` generation.
f. External Services & Utilities
- Docker/Podman engine or libvirt/QEMU/KVM.
- Host package dependencies (curl, dialog, freerdp3-x11, iproute2, libnotify-bin, netcat).

##### Relationships and Data Flows
- The CLI (`bin/winapps`) reads the user’s config, selects the backend, ensures the Windows VM is running.
- The backend layer (Docker/Podman/libvirt) launches or resumes the Windows VM.
- A scanning script inside the Windows VM collects installed `.exe` data and returns it to the host.
- When the user clicks a shortcut, the CLI invokes FreeRDP with flags and the target application’s RDP “RemoteApp” UUID.
- FreeRDP establishes an RDP stream to the Windows VM, tunneling the individual app window to the host display.
- The Linux file manager extension (Nautilus integration) uses the generated MIME mappings to dispatch files to Windows apps.
- The optional WinApps Launcher UI communicates with the CLI to start/stop/pause the VM and list installed apps.

##### Architectural Patterns and Design Principles
- Modular plug-in structure: each application supported under apps/ acts as an independent definition module.
- Backend abstraction: uniform CLI commands regardless of Docker/Podman/libvirt choice.
- Separation of concerns:
- Installer (setup.sh, install/) vs. runtime CLI vs. user config vs. definition modules vs. optional GUI.
- Data flow: config → backend orchestration → VM state → scanning → shortcut generation → RDP launch.
- Idempotent installation: re-running the installer cleans and updates definitions.
- Declarative packaging: Nix flake files under default.nix, flake.nix, packages/ for reproducible installs.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Host Side
  subgraph "Host Side"
    CLI["Host CLI"]:::hostExec
    Config["Configuration\n(~/.config/winapps/)"]:::storage
    subgraph "Installer"
      SetupScript["setup.sh"]:::hostExec
      InstallDir["install/"]:::hostExec
    end
    DesktopInt["Desktop Integration\n(.desktop & MIME)"]:::host
  end

  %% Declarative Packaging
  subgraph "Declarative Packaging"
    Nix1["default.nix"]:::nix
    Nix2["flake.nix"]:::nix
    Nix3["flake.lock"]:::nix
    Nix4["packages/winapps/default.nix"]:::nix
    Nix5["packages/winapps/setup.patch"]:::nix
  end

  %% Optional Tray UI
  subgraph "Optional Tray UI"
    TrayDir["packages/winapps-launcher/"]:::ui
    Nix6["packages/winapps-launcher/default.nix"]:::ui
    PatchUI["WinApps-Launcher.patch"]:::ui
  end

  %% Backend Abstraction
  subgraph "Virtualization Backend Abstraction"
    subgraph "Docker/Podman"
      Compose["compose.yaml"]:::backend
      DockerDoc["docs/docker.md"]:::backend
    end
    subgraph "libvirt"
      LibvirtDoc["docs/libvirt.md"]:::backend
      OEM["oem/"]:::backend
    end
    Manual["Manual Mode"]:::backend
  end

  %% Windows VM
  subgraph "Windows VM/Container"
    VM["Windows VM\n(RDP server)"]:::vm
    Scan["Scanning Script\n(collect .exe data)"]:::vm
  end

  %% Application Modules
  subgraph "Application Definition Modules"
    AppsDir["apps/"]:::storage
    DesktopMod["ms-office-protocol-handler.desktop"]:::modules
  end

  %% FreeRDP Transport
  subgraph "FreeRDP Transport"
    FreeRDP["FreeRDP Client\n(xfreerdp)"]:::rdp
  end

  HostDisplay["Host Display\n(X11/Wayland)"]:::host

  %% Connections
  CLI -->|reads config| Config
  CLI -->|runs installer| SetupScript
  CLI -->|runs installer| InstallDir
  CLI -->|selects backend| Compose
  CLI -->|selects backend| LibvirtDoc
  CLI -->|selects backend| Manual
  Compose --> VM
  DockerDoc --> Compose
  LibvirtDoc --> VM
  OEM --> LibvirtDoc
  Manual --> VM
  VM -->|return app list| CLI
  Scan -->|return data| CLI
  CLI -->|generate| DesktopMod
  AppsDir --> DesktopMod
  DesktopMod --> DesktopInt
  DesktopInt -->|launch app| CLI
  CLI -->|invoke| FreeRDP
  FreeRDP <-->|RDP Stream| VM
  FreeRDP -->|render window| HostDisplay
  CLI <--> TrayDir
  TrayDir --> Nix6
  TrayDir --> PatchUI
  CLI --> Nix1
  CLI --> Nix2
  CLI --> Nix3
  CLI --> Nix4
  CLI --> Nix5

  %% Click Events
  click CLI "https://github.com/winapps-org/winapps/tree/main/bin/winapps"
  click SetupScript "https://github.com/winapps-org/winapps/blob/main/setup.sh"
  click InstallDir "https://github.com/winapps-org/winapps/tree/main/install/"
  click Compose "https://github.com/winapps-org/winapps/blob/main/compose.yaml"
  click DockerDoc "https://github.com/winapps-org/winapps/blob/main/docs/docker.md"
  click LibvirtDoc "https://github.com/winapps-org/winapps/blob/main/docs/libvirt.md"
  click OEM "https://github.com/winapps-org/winapps/tree/main/oem/"
  click AppsDir "https://github.com/winapps-org/winapps/tree/main/apps/"
  click DesktopMod "https://github.com/winapps-org/winapps/blob/main/apps/ms-office-protocol-handler.desktop"
  click TrayDir "https://github.com/winapps-org/winapps/tree/main/packages/winapps-launcher/"
  click Nix1 "https://github.com/winapps-org/winapps/blob/main/default.nix"
  click Nix2 "https://github.com/winapps-org/winapps/blob/main/flake.nix"
  click Nix3 "https://github.com/winapps-org/winapps/blob/main/flake.lock"
  click Nix4 "https://github.com/winapps-org/winapps/blob/main/packages/winapps/default.nix"
  click Nix5 "https://github.com/winapps-org/winapps/blob/main/packages/winapps/setup.patch"
  click Nix6 "https://github.com/winapps-org/winapps/blob/main/packages/winapps-launcher/default.nix"
  click PatchUI "https://github.com/winapps-org/winapps/blob/main/packages/winapps-launcher/WinApps-Launcher.patch"

  %% Styles
  classDef host fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
  classDef hostExec fill:#90caf9,stroke:#1565c0,color:#0d47a1;
  classDef storage fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
  classDef backend fill:#c5e1a5,stroke:#558b2f,color:#33691e;
  classDef vm fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
  classDef vmNode fill:#ffcc80,stroke:#f57c00,color:#e65100;
  classDef modules fill:#e1bee7,stroke:#8e24aa,color:#6a1b9a;
  classDef rdp fill:#d1c4e9,stroke:#5e35b1,color:#311b92;
  classDef nix fill:#f0f4c3,stroke:#afb42b,color:#827717;
  classDef ui fill:#f8bbd0,stroke:#c2185b,color:#880e4f;
```
