# rafael7277/proxypilot architecture

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

- Interactive diagram: https://gitdiagram.com/rafael7277/proxypilot
- Repository: https://github.com/rafael7277/proxypilot

## Overview

ProxyPilot’s main workflow is to configure an app’s requested route, launch or observe the app, and report what process, socket, and bridge-event evidence actually shows. The loopback HTTP/CONNECT bridge forwards supported traffic to an optional SOCKS5 upstream; it is not transparent interception. CLI and GTK clients share an application API, while legacy desktop entry points remain. The graph preserves documented process review, system-proxy management, diagnostics, telemetry, and update checking; unsampled internals are represented conservatively.

Main entry points: [`src/proxypilot_app/api.py`](https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/api.py) (Shared API), [`proxypilot.py`](https://github.com/rafael7277/proxypilot/blob/main/proxypilot.py) (Proxy bridge and policy), [`checkui.py`](https://github.com/rafael7277/proxypilot/blob/main/checkui.py) (App check view), [`src/proxypilot_app/gtk_ui.py`](https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/gtk_ui.py) (GTK client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Administration clients"]
  node_cli["Headless CLI<br/>[cli.py]"]
  node_gtk["GTK client<br/>[gtk_ui.py]"]
  node_legacy_ui["Legacy desktop UI<br/>[desktop.py]"]
  node_api["Shared API<br/>[api.py]"]
  node_updates["Release check<br/>[updates.py]"]
  node_app_icons["App icons<br/>[appicons.py]"]
  node_check_ui["App check view<br/>[checkui.py]"]
end

subgraph group_routing["Routing and policy"]
  node_policy_bridge["Proxy bridge and policy<br/>[proxypilot.py]"]
  node_traffic[("Bridge telemetry<br/>[traffic.py]")]
end

subgraph group_evidence["Observation and diagnostics"]
  node_socket_watch["Socket watcher<br/>[socketwatch.py]"]
  node_socket_observe["TCP socket attribution<br/>[netobserve.py]"]
  node_app_evidence["Route evidence<br/>[appstatus.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
end

subgraph group_operations["System operations"]
  node_inventory["App and process inventory<br/>[manager.py]"]
  node_system_proxy["System proxy settings<br/>[proxypilot.py]"]
  node_uninstaller["Uninstaller<br/>[uninstall.py]"]
end

node_user(("User / SSH"))
node_desktop_user(("Desktop user"))
node_applications(("Proxy-aware apps"))
node_socks(("SOCKS5 upstream"))

node_user -->|"runs commands"| node_cli
node_desktop_user -->|"opens client"| node_gtk
node_applications -->|"uses configured proxy"| node_policy_bridge
node_policy_bridge -->|"forwards traffic"| node_socks
node_cli -->|"calls"| node_api
node_gtk -->|"uses shared API"| node_api
node_legacy_ui -->|"manages routes"| node_policy_bridge
node_api -->|"queries inventory"| node_inventory
node_api -->|"queries diagnostics"| node_diagnostics
node_api -->|"queries sockets"| node_socket_observe
node_api -->|"reads bridge status"| node_policy_bridge
node_api -->|"reads events"| node_traffic
node_api -->|"checks releases"| node_updates
node_policy_bridge -->|"records events"| node_traffic
node_inventory -->|"applies app routes"| node_policy_bridge
node_socket_watch -.->|"samples sockets"| node_socket_observe
node_check_ui -->|"evaluates observations"| node_app_evidence
node_check_ui -->|"requests snapshot"| node_diagnostics
node_check_ui -.->|"uses observations"| node_socket_observe
node_check_ui -->|"reads events"| node_traffic
node_desktop_user -.->|"opens legacy UI"| node_legacy_ui
node_app_icons -.->|"supplies icons"| node_gtk

click node_cli "https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/cli.py"
click node_gtk "https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/gtk_ui.py"
click node_legacy_ui "https://github.com/rafael7277/proxypilot/blob/main/desktop.py"
click node_api "https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/api.py"
click node_updates "https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/updates.py"
click node_policy_bridge "https://github.com/rafael7277/proxypilot/blob/main/proxypilot.py"
click node_traffic "https://github.com/rafael7277/proxypilot/blob/main/traffic.py"
click node_inventory "https://github.com/rafael7277/proxypilot/blob/main/manager.py"
click node_system_proxy "https://github.com/rafael7277/proxypilot/blob/main/proxypilot.py"
click node_uninstaller "https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/uninstall.py"
click node_socket_watch "https://github.com/rafael7277/proxypilot/blob/main/socketwatch.py"
click node_socket_observe "https://github.com/rafael7277/proxypilot/blob/main/netobserve.py"
click node_app_evidence "https://github.com/rafael7277/proxypilot/blob/main/appstatus.py"
click node_diagnostics "https://github.com/rafael7277/proxypilot/blob/main/diagnostics.py"
click node_app_icons "https://github.com/rafael7277/proxypilot/blob/main/appicons.py"
click node_check_ui "https://github.com/rafael7277/proxypilot/blob/main/checkui.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_gtk,node_legacy_ui,node_api,node_updates,node_app_icons,node_check_ui,node_user,node_desktop_user toneBlue
class node_policy_bridge,node_traffic toneAmber
class node_socket_watch,node_socket_observe,node_app_evidence,node_diagnostics toneMint
class node_inventory,node_system_proxy,node_uninstaller toneRose
class node_applications,node_socks toneIndigo
```

## Components

### Administration clients

- [Headless CLI](https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/cli.py): `src/proxypilot_app/cli.py`
- [GTK client](https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/gtk_ui.py): `src/proxypilot_app/gtk_ui.py`
- [Legacy desktop UI](https://github.com/rafael7277/proxypilot/blob/main/desktop.py): `desktop.py`
- [Shared API](https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/api.py): `src/proxypilot_app/api.py`
- [Release check](https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/updates.py): `src/proxypilot_app/updates.py`
- [App icons](https://github.com/rafael7277/proxypilot/blob/main/appicons.py): `appicons.py`
- [App check view](https://github.com/rafael7277/proxypilot/blob/main/checkui.py): `checkui.py`

### Routing and policy

- [Proxy bridge and policy](https://github.com/rafael7277/proxypilot/blob/main/proxypilot.py): `proxypilot.py`
- [Bridge telemetry](https://github.com/rafael7277/proxypilot/blob/main/traffic.py): `traffic.py`

### Observation and diagnostics

- [Socket watcher](https://github.com/rafael7277/proxypilot/blob/main/socketwatch.py): `socketwatch.py`
- [TCP socket attribution](https://github.com/rafael7277/proxypilot/blob/main/netobserve.py): `netobserve.py`
- [Route evidence](https://github.com/rafael7277/proxypilot/blob/main/appstatus.py): `appstatus.py`
- [Diagnostics](https://github.com/rafael7277/proxypilot/blob/main/diagnostics.py): `diagnostics.py`

### System operations

- [App and process inventory](https://github.com/rafael7277/proxypilot/blob/main/manager.py): `manager.py`
- [System proxy settings](https://github.com/rafael7277/proxypilot/blob/main/proxypilot.py): `proxypilot.py`
- [Uninstaller](https://github.com/rafael7277/proxypilot/blob/main/src/proxypilot_app/uninstall.py): `src/proxypilot_app/uninstall.py`

### Other components

- **User / SSH**
- **Desktop user**
- **Proxy-aware apps**
- **SOCKS5 upstream**

## Connections

- User / SSH → Headless CLI: runs commands (evidence: `README.md`)
- Desktop user → GTK client: opens client (evidence: `README.md`)
- Proxy-aware apps → Proxy bridge and policy: uses configured proxy (evidence: `README.md`)
- Proxy bridge and policy → SOCKS5 upstream: forwards traffic (evidence: `README.md`)
- Headless CLI → Shared API: calls (evidence: `src/proxypilot_app/cli.py`)
- GTK client → Shared API: uses shared API (evidence: `src/proxypilot_app/gtk_ui.py`)
- Legacy desktop UI → Proxy bridge and policy: manages routes (evidence: `desktop.py`)
- Shared API → App and process inventory: queries inventory (evidence: `src/proxypilot_app/api.py`)
- Shared API → Diagnostics: queries diagnostics (evidence: `src/proxypilot_app/api.py`)
- Shared API → TCP socket attribution: queries sockets (evidence: `src/proxypilot_app/api.py`)
- Shared API → Proxy bridge and policy: reads bridge status (evidence: `src/proxypilot_app/api.py`)
- Shared API → Bridge telemetry: reads events (evidence: `src/proxypilot_app/api.py`)
- Shared API → Release check: checks releases (evidence: `src/proxypilot_app/api.py`)
- Proxy bridge and policy → Bridge telemetry: records events (evidence: `proxypilot.py`)
- App and process inventory → Proxy bridge and policy: applies app routes (evidence: `manager.py`)
- Socket watcher → TCP socket attribution: samples sockets
- App check view → Route evidence: evaluates observations (evidence: `checkui.py`)
- App check view → Diagnostics: requests snapshot (evidence: `checkui.py`)
- App check view → TCP socket attribution: uses observations (evidence: `checkui.py`)
- App check view → Bridge telemetry: reads events (evidence: `checkui.py`)
- Desktop user → Legacy desktop UI: opens legacy UI
- App icons → GTK client: supplies icons