# protonvpn/proton-vpn-gtk-app architecture

> Architecture diagram of the GitHub repository protonvpn/proton-vpn-gtk-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/protonvpn/proton-vpn-gtk-app
- Repository: https://github.com/protonvpn/proton-vpn-gtk-app

## Overview

##### Project type and purpose
- This is a desktop GUI application (GTK) written in Python.
- Its purpose is to provide an end-user interface for Proton VPN service: authenticate users, list servers, establish/monitor VPN connections, handle reconnection logic, and surface status & notifications.

##### File structure
- Top-level directories:
- debian, rpmbuild → packaging metadata and scripts for .deb/.rpm builds
- proton/vpn/app/gtk → main application code
- scripts → versioning and changelog automation
- tests → integration (Behave) and unit tests
- Inside proton/vpn/app/gtk:
- app.py, __main__.py → entry point
- controller.py + config.py → application orchestration & configuration
- widgets/… → UI components grouped by screen/feature (login, main, vpn, headerbar menus)
- services/reconnector/… → background monitors (session, network, VPN) and reconnection logic
- utils/… → helper modules (executor, exception_handler, glib wrappers, semver, etc.)
- Packaging & CI files (setup.py, setup.cfg, .gitlab-ci.yml) configure build, test, and release pipelines.

##### README for additional insights
- Confirms GTK-based front end for Proton VPN users
- Describes virtual environment and custom PyPI registry
- Explains where logs (~/.cache/Proton/VPN/logs) and user settings (~/.config/Proton/VPN) live
- Outlines how to run unit tests (pytest/unittest) and integration tests (Behave, Xvfb)
- Versioning automated via versions.yml + custom scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% User & OS
  subgraph "User & OS"
    User["User"]:::external
    OS["OS Networking / VPN Kernel / CLI"]:::external
  end

  %% UI Layer
  subgraph "GTK UI Layer"
    AppEntry["app.py / __main__.py"]:::ui
    Widgets["Widgets (login, main, server list, notifications)"]:::ui
    Headerbar["Headerbar & Dialogs"]:::ui
    Assets["Assets"]:::ui
  end

  %% Controller & Config
  subgraph "Controller & Config"
    Controller["controller.py"]:::service
    Config["config.py"]:::service
  end

  %% Service Layer
  subgraph "Service Layer"
    NM["network_monitor.py"]:::service
    SM["session_monitor.py"]:::service
    VM["vpn_monitor.py"]:::service
    RC["reconnector.py"]:::service
  end

  %% Utility Layer
  subgraph "Utility Layer"
    UtilFile["util.py"]:::util
    UtilsDir["utils/"]:::util
  end

  %% Data & Persistence
  subgraph "Data & Persistence"
    ConfDir["User Settings (~/.config/Proton/VPN)"]:::storage
    LogDir["Logs (~/.cache/Proton/VPN/logs)"]:::storage
  end

  %% External Services
  subgraph "External Services"
    API["Proton VPN API"]:::external
    PyPI["Private PyPI Registry"]:::external
  end

  %% Development & Delivery
  subgraph "Development & Delivery"
    Debian["debian/"]:::delivery
    RPM["rpmbuild/"]:::delivery
    Scripts["scripts/"]:::delivery
    SetupPy["setup.py / setup.cfg"]:::delivery
    CI[".gitlab-ci.yml"]:::delivery
    IntegrationTests["tests/integration/"]:::delivery
    UnitTests["tests/unit/"]:::delivery
  end

  %% Connections
  User -->|clicks| Widgets
  Widgets -->|UI events| Controller
  Headerbar -->|menu actions| Controller
  AppEntry -->|starts| Controller
  Controller -->|calls| NM
  Controller -->|calls| SM
  Controller -->|calls| VM
  Controller -->|calls| RC
  NM -->|event| Controller
  SM -->|event| Controller
  VM -->|event| Controller
  RC -->|triggers reconnection| Controller
  Controller -->|uses| UtilFile
  Controller -->|uses| UtilsDir
  NM -->|uses| UtilFile
  NM -->|uses| UtilsDir
  SM -->|uses| UtilFile
  SM -->|uses| UtilsDir
  VM -->|uses| UtilFile
  VM -->|uses| UtilsDir
  RC -->|uses| UtilFile
  RC -->|uses| UtilsDir
  Controller -->|read/write| ConfDir
  NM -->|log| LogDir
  SM -->|log| LogDir
  VM -->|log| LogDir
  RC -->|log| LogDir
  Controller -->|config| Config
  Config -->|stores prefs| ConfDir
  Controller -->|API calls| API
  NM -->|API calls| API
  SM -->|API calls| API
  VM -->|API calls| API
  RC -->|API calls| API
  Controller -->|install deps| PyPI
  Debian -->|build| RPM
  Scripts -->|version| SetupPy
  CI -->|orchestrates| Debian
  CI -->|orchestrates| RPM
  CI -->|runs| IntegrationTests
  CI -->|runs| UnitTests

  %% Click Events
  click Widgets "https://github.com/protonvpn/proton-vpn-gtk-app/tree/stable/proton/vpn/app/gtk/widgets/"
  click AppEntry "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/proton/vpn/app/gtk/app.py"
  click Assets "https://github.com/protonvpn/proton-vpn-gtk-app/tree/stable/proton/vpn/app/gtk/assets/"
  click Controller "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/proton/vpn/app/gtk/controller.py"
  click Config "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/proton/vpn/app/gtk/config.py"
  click NM "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/proton/vpn/app/gtk/services/reconnector/network_monitor.py"
  click SM "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/proton/vpn/app/gtk/services/reconnector/session_monitor.py"
  click VM "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/proton/vpn/app/gtk/services/reconnector/vpn_monitor.py"
  click RC "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/proton/vpn/app/gtk/services/reconnector/reconnector.py"
  click UtilFile "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/proton/vpn/app/gtk/util.py"
  click UtilsDir "https://github.com/protonvpn/proton-vpn-gtk-app/tree/stable/proton/vpn/app/gtk/utils/"
  click Debian "https://github.com/protonvpn/proton-vpn-gtk-app/tree/stable/debian/"
  click RPM "https://github.com/protonvpn/proton-vpn-gtk-app/tree/stable/rpmbuild/"
  click Scripts "https://github.com/protonvpn/proton-vpn-gtk-app/tree/stable/scripts/"
  click SetupPy "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/setup.py"
  click CI "https://github.com/protonvpn/proton-vpn-gtk-app/blob/stable/.gitlab-ci.yml"
  click IntegrationTests "https://github.com/protonvpn/proton-vpn-gtk-app/tree/stable/tests/integration/"
  click UnitTests "https://github.com/protonvpn/proton-vpn-gtk-app/tree/stable/tests/unit/"

  %% Styles
  classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef service fill:#90EE90,stroke:#333,stroke-width:1px
  classDef util fill:#FFA500,stroke:#333,stroke-width:1px
  classDef storage fill:#F4A460,stroke:#333,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
  classDef delivery fill:#E6E6FA,stroke:#333,stroke-width:1px
```
