# dgac/padsi architecture

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

- Interactive diagram: https://gitdiagram.com/dgac/padsi
- Repository: https://github.com/dgac/padsi

## Overview

PADSI is a Linux desktop security package that runs applications in configured, isolated zones and can also manage zone-constrained virtual machines. The principal workflow is: a user launches an application through the PADSI CLI, zone configuration determines its environment and policies, and the per-user runtime starts the application bubble and supporting infrastructure. Network filtering, shared files, visual zone identification, and optional VPN, web-proxy, and VM features extend that workflow. The README documents the product-level flow; sampled source verifies selected networking, proxy, VM-agent, and eBPF components, so uncertain internal wiring is omitted.

Main entry points: [`padsi/run`](https://github.com/dgac/padsi/tree/main/padsi/run) (Zone runtime), [`padsi/run/network_infra.py`](https://github.com/dgac/padsi/blob/main/padsi/run/network_infra.py) (Network infrastructure), [`padsi/run/vm`](https://github.com/dgac/padsi/tree/main/padsi/run/vm) (VM management), [`crates/init/src/main.rs`](https://github.com/dgac/padsi/blob/main/crates/init/src/main.rs) (Bubble init)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch and zones"]
  node_cli["PADSI CLI<br/>[client.py]"]
  node_zone_config["Zone configuration<br/>[main.py]"]
  node_zone_runtime["Zone runtime"]
end

subgraph group_isolation["Isolation and files"]
  node_bubble_init["Bubble init<br/>[main.rs]"]
  node_bubblewrap["Bubblewrap"]
  node_mount_config["Mount policies<br/>[mountpoint.py]"]
  node_data_guard["Data access guard<br/>[main.rs]"]
  node_data_guard_ebpf["File access hooks<br/>[main.rs]"]
end

subgraph group_network["Network controls"]
  node_network_config["Network policies<br/>[network.py]"]
  node_network_runtime["Network infrastructure<br/>[network_infra.py]"]
  node_firewall["Firewall rules<br/>[firewall.py]"]
  node_input_manager["Host input rules"]
  node_traffic_shapers["VPN traffic shapers<br/>[trafficshaper.py]"]
  node_web_infra["Web proxy services<br/>[main.rs]"]
end

subgraph group_desktop["Desktop services"]
  node_wayland["Wayland proxy<br/>[main.rs]"]
  node_clipboard_config["Clipboard policies<br/>[clipboard.py]"]
  node_visual_feedback["Zone visual feedback"]
end

subgraph group_vm["Virtual machines"]
  node_vm_config["VM configuration<br/>[vm.py]"]
  node_vm_runtime["VM management"]
  node_vm_agent["VM guest agent<br/>[main.rs]"]
end

node_user(("Desktop user"))
node_external_services(("VPN and web services"))

node_user -->|"launches"| node_cli
node_cli -->|"requests run"| node_zone_runtime
node_zone_runtime -->|"reads policies"| node_zone_config
node_zone_runtime -->|"starts bubble"| node_bubble_init
node_bubble_init -->|"creates isolation"| node_bubblewrap
node_zone_runtime -->|"applies mounts"| node_mount_config
node_bubble_init -->|"constrained by"| node_data_guard
node_data_guard -->|"loads hooks"| node_data_guard_ebpf
node_zone_runtime -->|"starts support"| node_network_runtime
node_network_runtime -->|"reads policies"| node_network_config
node_network_runtime -->|"configures rules"| node_firewall
node_input_manager -->|"sets input rules"| node_firewall
node_network_runtime -.->|"configures routing"| node_traffic_shapers
node_network_runtime -.->|"starts proxy services"| node_web_infra
node_external_services -.->|"serves proxy traffic"| node_web_infra
node_zone_runtime -.->|"starts proxy"| node_wayland
node_wayland -->|"enforces sharing"| node_clipboard_config
node_zone_runtime -->|"provides zone identity"| node_visual_feedback
node_user -->|"manages VMs"| node_vm_runtime
node_vm_runtime -->|"reads templates"| node_vm_config
node_vm_runtime -->|"communicates with guest"| node_vm_agent
node_vm_runtime -->|"runs within zone"| node_zone_runtime

click node_cli "https://github.com/dgac/padsi/blob/main/padsi/cli/client.py"
click node_zone_config "https://github.com/dgac/padsi/blob/main/padsi/config/main.py"
click node_zone_runtime "https://github.com/dgac/padsi/tree/main/padsi/run"
click node_bubble_init "https://github.com/dgac/padsi/blob/main/crates/init/src/main.rs"
click node_mount_config "https://github.com/dgac/padsi/blob/main/padsi/config/mountpoint.py"
click node_data_guard "https://github.com/dgac/padsi/blob/main/crates/data-access-guard/data-access-guard/src/main.rs"
click node_data_guard_ebpf "https://github.com/dgac/padsi/blob/main/crates/data-access-guard/data-access-guard-ebpf/src/main.rs"
click node_network_config "https://github.com/dgac/padsi/blob/main/padsi/config/network.py"
click node_network_runtime "https://github.com/dgac/padsi/blob/main/padsi/run/network_infra.py"
click node_firewall "https://github.com/dgac/padsi/blob/main/padsi/fwlib/firewall.py"
click node_input_manager "https://github.com/dgac/padsi/blob/main/padsi/system/network_input_manager.py"
click node_traffic_shapers "https://github.com/dgac/padsi/blob/main/padsi/config/trafficshaper.py"
click node_web_infra "https://github.com/dgac/padsi/blob/main/crates/web-infra/src/main.rs"
click node_wayland "https://github.com/dgac/padsi/blob/main/crates/wayland-proxy/src/main.rs"
click node_clipboard_config "https://github.com/dgac/padsi/blob/main/padsi/config/clipboard.py"
click node_visual_feedback "https://github.com/dgac/padsi/tree/main/padsi/run/components"
click node_vm_config "https://github.com/dgac/padsi/blob/main/padsi/config/vm.py"
click node_vm_runtime "https://github.com/dgac/padsi/tree/main/padsi/run/vm"
click node_vm_agent "https://github.com/dgac/padsi/blob/main/crates/vm-agent/src/main.rs"

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_zone_config,node_zone_runtime,node_user toneBlue
class node_bubble_init,node_bubblewrap,node_mount_config,node_data_guard,node_data_guard_ebpf toneAmber
class node_network_config,node_network_runtime,node_firewall,node_input_manager,node_traffic_shapers,node_web_infra toneMint
class node_wayland,node_clipboard_config,node_visual_feedback toneRose
class node_vm_config,node_vm_runtime,node_vm_agent,node_external_services toneIndigo
```

## Components

### Launch and zones

- [PADSI CLI](https://github.com/dgac/padsi/blob/main/padsi/cli/client.py): `padsi/cli/client.py`
- [Zone configuration](https://github.com/dgac/padsi/blob/main/padsi/config/main.py): `padsi/config/main.py`
- [Zone runtime](https://github.com/dgac/padsi/tree/main/padsi/run): `padsi/run`

### Isolation and files

- [Bubble init](https://github.com/dgac/padsi/blob/main/crates/init/src/main.rs): `crates/init/src/main.rs`
- **Bubblewrap**
- [Mount policies](https://github.com/dgac/padsi/blob/main/padsi/config/mountpoint.py): `padsi/config/mountpoint.py`
- [Data access guard](https://github.com/dgac/padsi/blob/main/crates/data-access-guard/data-access-guard/src/main.rs): `crates/data-access-guard/data-access-guard/src/main.rs`
- [File access hooks](https://github.com/dgac/padsi/blob/main/crates/data-access-guard/data-access-guard-ebpf/src/main.rs): `crates/data-access-guard/data-access-guard-ebpf/src/main.rs`

### Network controls

- [Network policies](https://github.com/dgac/padsi/blob/main/padsi/config/network.py): `padsi/config/network.py`
- [Network infrastructure](https://github.com/dgac/padsi/blob/main/padsi/run/network_infra.py): `padsi/run/network_infra.py`
- [Firewall rules](https://github.com/dgac/padsi/blob/main/padsi/fwlib/firewall.py): `padsi/fwlib/firewall.py`
- [Host input rules](https://github.com/dgac/padsi/blob/main/padsi/system/network_input_manager.py): `padsi/system/network_input_manager.py`
- [VPN traffic shapers](https://github.com/dgac/padsi/blob/main/padsi/config/trafficshaper.py): `padsi/config/trafficshaper.py`
- [Web proxy services](https://github.com/dgac/padsi/blob/main/crates/web-infra/src/main.rs): `crates/web-infra/src/main.rs`

### Desktop services

- [Wayland proxy](https://github.com/dgac/padsi/blob/main/crates/wayland-proxy/src/main.rs): `crates/wayland-proxy/src/main.rs`
- [Clipboard policies](https://github.com/dgac/padsi/blob/main/padsi/config/clipboard.py): `padsi/config/clipboard.py`
- [Zone visual feedback](https://github.com/dgac/padsi/tree/main/padsi/run/components): `padsi/run/components`

### Virtual machines

- [VM configuration](https://github.com/dgac/padsi/blob/main/padsi/config/vm.py): `padsi/config/vm.py`
- [VM management](https://github.com/dgac/padsi/tree/main/padsi/run/vm): `padsi/run/vm`
- [VM guest agent](https://github.com/dgac/padsi/blob/main/crates/vm-agent/src/main.rs): `crates/vm-agent/src/main.rs`

### Other components

- **Desktop user**
- **VPN and web services**

## Connections

- Desktop user → PADSI CLI: launches
- PADSI CLI → Zone runtime: requests run
- Zone runtime → Zone configuration: reads policies
- Zone runtime → Bubble init: starts bubble
- Bubble init → Bubblewrap: creates isolation
- Zone runtime → Mount policies: applies mounts
- Bubble init → Data access guard: constrained by
- Data access guard → File access hooks: loads hooks
- Zone runtime → Network infrastructure: starts support
- Network infrastructure → Network policies: reads policies
- Network infrastructure → Firewall rules: configures rules
- Host input rules → Firewall rules: sets input rules
- Network infrastructure → VPN traffic shapers: configures routing
- Network infrastructure → Web proxy services: starts proxy services
- VPN and web services → Web proxy services: serves proxy traffic
- Zone runtime → Wayland proxy: starts proxy
- Wayland proxy → Clipboard policies: enforces sharing
- Zone runtime → Zone visual feedback: provides zone identity
- Desktop user → VM management: manages VMs
- VM management → VM configuration: reads templates
- VM management → VM guest agent: communicates with guest
- VM management → Zone runtime: runs within zone