# kernalix7/winpodx architecture

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

- Interactive diagram: https://gitdiagram.com/kernalix7/winpodx
- Repository: https://github.com/kernalix7/winpodx

## Overview

WinPodX runs Windows apps in a containerized guest and presents them as native Linux applications. The primary workflow is setup and provisioning, guest app discovery, desktop-entry registration, then launching an app through a FreeRDP RemoteApp session. The repository also includes a GUI/tray dashboard, host-device and VM controls, and reverse-open file/URL integration. Edges reflect README statements or relationships listed in the SOURCE INDEX; unsampled implementation details are not inferred beyond those documented connections.

Main entry points: [`src/winpodx/cli/setup_cmd.py`](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/cli/setup_cmd.py) (Setup wizard), [`src/winpodx/desktop/entry.py`](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/desktop/entry.py) (Desktop entries), [`src/winpodx/cli/main.py`](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/cli/main.py) (CLI), [`src/winpodx/core/discovery/__init__.py`](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/discovery/__init__.py) (App discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and VM"]
  node_cli["CLI<br/>[main.py]"]
  node_setupflow["Setup wizard<br/>[setup_cmd.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_provision["Provisioning<br/>[provisioner.py]"]
  node_backend["Container backend<br/>[podman.py]"]
  node_compose["VM compose<br/>[compose.py]"]
end

subgraph group_guest["Guest apps"]
  node_guest["Windows guest"]
  node_discovery["App discovery<br/>[__init__.py]"]
  node_catalog["App catalog<br/>[app.py]"]
  node_windows_exec["Windows execution<br/>[windows_exec.py]"]
  node_transport["Transport dispatch<br/>[dispatch.py]"]
  node_rdp["FreeRDP sessions<br/>[rdp.py]"]
  node_app_cli["App commands<br/>[app.py]"]
end

subgraph group_desktop["Linux desktop"]
  node_gui["GUI<br/>[main_window.py]"]
  node_desktop_entries["Desktop entries<br/>[entry.py]"]
  node_icons["Icon management<br/>[icons.py]"]
  node_tray["Tray launcher<br/>[tray.py]"]
end

subgraph group_integrations["Host integrations"]
  node_devices["Device controls<br/>[devices.py]"]
  node_reverse_open["Reverse-open<br/>[listener.py]"]
  node_host["Linux desktop"]
end

node_user(("User"))

node_user -->|"runs commands"| node_cli
node_user -->|"opens dashboard"| node_gui
node_cli -->|"routes setup"| node_setupflow
node_setupflow -->|"writes config"| node_config
node_setupflow -->|"starts provisioning"| node_provision
node_provision -->|"controls pod"| node_backend
node_backend -->|"runs compose"| node_compose
node_compose -->|"creates VM"| node_guest
node_setupflow -->|"discovers apps"| node_discovery
node_discovery -->|"queries apps"| node_guest
node_discovery -->|"persists results"| node_catalog
node_cli -->|"routes app commands"| node_app_cli
node_app_cli -->|"manages apps"| node_catalog
node_app_cli -->|"registers entries"| node_desktop_entries
node_desktop_entries -->|"reads app data"| node_catalog
node_desktop_entries -->|"uses icons"| node_icons
node_host -->|"shows launchers"| node_desktop_entries
node_user -->|"launches app"| node_host
node_windows_exec -->|"dispatches execution"| node_transport
node_transport -->|"selects transport"| node_rdp
node_rdp -->|"opens RemoteApp"| node_guest
node_gui -->|"runs setup"| node_provision
node_gui -->|"controls devices"| node_devices
node_guest -.->|"sends open requests"| node_reverse_open
node_reverse_open -.->|"opens host files"| node_host

click node_cli "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/cli/main.py"
click node_gui "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/gui/main_window.py"
click node_setupflow "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/cli/setup_cmd.py"
click node_config "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/config.py"
click node_provision "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/provisioner.py"
click node_backend "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/backend/podman.py"
click node_compose "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/pod/compose.py"
click node_discovery "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/discovery/__init__.py"
click node_catalog "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/app.py"
click node_windows_exec "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/windows_exec.py"
click node_transport "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/transport/dispatch.py"
click node_rdp "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/rdp.py"
click node_app_cli "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/cli/app.py"
click node_desktop_entries "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/desktop/entry.py"
click node_icons "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/desktop/icons.py"
click node_tray "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/desktop/tray.py"
click node_devices "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/devices.py"
click node_reverse_open "https://github.com/kernalix7/winpodx/blob/main/src/winpodx/reverse_open/listener.py"

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_cli,node_setupflow,node_config,node_provision,node_backend,node_compose,node_user toneBlue
class node_guest,node_discovery,node_catalog,node_windows_exec,node_transport,node_rdp,node_app_cli toneAmber
class node_gui,node_desktop_entries,node_icons,node_tray toneMint
class node_devices,node_reverse_open,node_host toneRose
```

## Components

### Setup and VM

- [CLI](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/cli/main.py): `src/winpodx/cli/main.py`
- [Setup wizard](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/cli/setup_cmd.py): `src/winpodx/cli/setup_cmd.py`
- [Configuration](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/config.py): `src/winpodx/core/config.py`
- [Provisioning](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/provisioner.py): `src/winpodx/core/provisioner.py`
- [Container backend](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/backend/podman.py): `src/winpodx/backend/podman.py`
- [VM compose](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/pod/compose.py): `src/winpodx/core/pod/compose.py`

### Guest apps

- **Windows guest**
- [App discovery](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/discovery/__init__.py): `src/winpodx/core/discovery/__init__.py`
- [App catalog](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/app.py): `src/winpodx/core/app.py`
- [Windows execution](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/windows_exec.py): `src/winpodx/core/windows_exec.py`
- [Transport dispatch](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/transport/dispatch.py): `src/winpodx/core/transport/dispatch.py`
- [FreeRDP sessions](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/rdp.py): `src/winpodx/core/rdp.py`
- [App commands](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/cli/app.py): `src/winpodx/cli/app.py`

### Linux desktop

- [GUI](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/gui/main_window.py): `src/winpodx/gui/main_window.py`
- [Desktop entries](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/desktop/entry.py): `src/winpodx/desktop/entry.py`
- [Icon management](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/desktop/icons.py): `src/winpodx/desktop/icons.py`
- [Tray launcher](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/desktop/tray.py): `src/winpodx/desktop/tray.py`

### Host integrations

- [Device controls](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/core/devices.py): `src/winpodx/core/devices.py`
- [Reverse-open](https://github.com/kernalix7/winpodx/blob/main/src/winpodx/reverse_open/listener.py): `src/winpodx/reverse_open/listener.py`
- **Linux desktop**

### Other components

- **User**

## Connections

- User → CLI: runs commands
- User → GUI: opens dashboard
- CLI → Setup wizard: routes setup (evidence: `src/winpodx/cli/main.py`)
- Setup wizard → Configuration: writes config
- Setup wizard → Provisioning: starts provisioning
- Provisioning → Container backend: controls pod (evidence: `src/winpodx/core/provisioner.py`)
- Container backend → VM compose: runs compose (evidence: `src/winpodx/backend/podman.py`)
- VM compose → Windows guest: creates VM
- Setup wizard → App discovery: discovers apps
- App discovery → Windows guest: queries apps (evidence: `src/winpodx/core/discovery/__init__.py`)
- App discovery → App catalog: persists results (evidence: `src/winpodx/core/discovery/__init__.py`)
- CLI → App commands: routes app commands (evidence: `src/winpodx/cli/main.py`)
- App commands → App catalog: manages apps (evidence: `src/winpodx/cli/app.py`)
- App commands → Desktop entries: registers entries (evidence: `src/winpodx/cli/app.py`)
- Desktop entries → App catalog: reads app data (evidence: `src/winpodx/desktop/entry.py`)
- Desktop entries → Icon management: uses icons (evidence: `src/winpodx/desktop/entry.py`)
- Linux desktop → Desktop entries: shows launchers
- User → Linux desktop: launches app
- Windows execution → Transport dispatch: dispatches execution (evidence: `src/winpodx/core/windows_exec.py`)
- Transport dispatch → FreeRDP sessions: selects transport
- FreeRDP sessions → Windows guest: opens RemoteApp
- GUI → Provisioning: runs setup
- GUI → Device controls: controls devices
- Windows guest → Reverse-open: sends open requests
- Reverse-open → Linux desktop: opens host files
