# houtadono/proxy-wright architecture

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

- Interactive diagram: https://gitdiagram.com/houtadono/proxy-wright
- Repository: https://github.com/houtadono/proxy-wright

## Overview

##### Project Type and Purpose
- Proxy-Wright is a desktop application (full-stack on the client side) for managing browser profiles and proxies, launching Playwright browsers with user-defined settings, and self-updating via GitHub Releases.
- Built in Python, it uses PySide6 for the UI, Playwright for browser automation, and an embedded 3proxy binary for SOCKS5 proxy support.

##### File Structure Analysis
- Top-level entrypoints:
- app.py (main application startup)
- app.spec / updater.spec (PyInstaller build specs)
- installer.iss (Inno Setup installer script)
- Configuration & core logic:
- config.py (static config values)
- core/ (paths.py, settings.py, updater.py)
- Data layer:
- data/db.py (SQLite or similar persistence)
- data/repo.py (repository pattern for profiles & settings)
- Service layer:
- services/browser_service.py (Playwright browser lifecycle)
- services/playwright_service.py (Playwright API wrapper)
- services/proxy_service.py (3proxy wrapper + native proxy config)
- services/qt_event_runner.py (bridging Qt’s event loop and async tasks)
- UI layer:
- ui/main_window.py
- ui/profile_dialog.py, proxy_dialog.py, setting_tab.py
- Background workers:
- workers/browser_worker.py
- workers/proxy_check_worker.py
- workers/update_worker.py
- Utilities & scripts:
- tools/updater_helper.py
- .github/scripts (release notes, cleanup)
- External binaries & assets:
- bin/3proxy.exe (embedded proxy server)

##### Key README Insights
- Multi-language support (via Qt .qm files)
- In-app update checking from GitHub
- Uses PyInstaller packaging, so bundling of dependencies and 3proxy.exe
- License restrictions (source-available, non-commercial)

##### Components
a. Frontend (UI)
- PySide6-based windows & dialogs
- Translations & resource loading
b. Business Logic / Controllers
- core/updater: checks & downloads new releases
- services/*: abstractions over Playwright, 3proxy, proxy setup
c. Data Persistence
- SQLite (or file-based DB) via data/db.py
- Repository layer (data/repo.py)
d. Background Workers
- Threads or QtConcurrent tasks for non-blocking operations
e. External Dependencies
- 3proxy.exe binary (launched as a subprocess)
- Playwright browsers (Chromium, Firefox, WebKit)
- GitHub Releases API (for update service)
f. Packaging & Deployment
- PyInstaller (app.spec, updater.spec)
- Inno Setup installer (installer.iss)

##### Relationships & Data Flow
- UI events → controllers in services or core → data repo or external processes
- Services spawn workers for I/O (network, proxy health check, browser launch)
- Workers report status back to UI via signals/events (qt_event_runner)
- Updater downloads new build → PyInstaller-generated updater.exe → restarts app
- 3proxy subprocess launched by proxy_service, managed by browser_service when launching browsers

##### Architectural Patterns & Design Principles
- MVC/MVP-like pattern: UI layer (View) separated from services (Controller) and data (Model)
- Repository pattern for data access
- Service layer for external integrations (Playwright, 3proxy)
- Asynchronous/background workers to keep UI responsive
- Single-page desktop UI with multiple dialog components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    Entrypoint["app.py"]:::service
    click Entrypoint "https://github.com/houtadono/proxy-wright/blob/main/app.py"

    %% UI Layer
    subgraph "UI Layer"
        MainWindow["MainWindow"]:::ui
        ProfileDialog["ProfileDialog"]:::ui
        ProxyDialog["ProxyDialog"]:::ui
        SettingsTab["SettingsTab"]:::ui
    end
    click MainWindow "https://github.com/houtadono/proxy-wright/blob/main/ui/main_window.py"
    click ProfileDialog "https://github.com/houtadono/proxy-wright/blob/main/ui/profile_dialog.py"
    click ProxyDialog "https://github.com/houtadono/proxy-wright/blob/main/ui/proxy_dialog.py"
    click SettingsTab "https://github.com/houtadono/proxy-wright/blob/main/ui/setting_tab.py"

    %% Core & Services
    subgraph "Core & Services"
        Config["config.py"]:::service
        Paths["paths"]:::service
        SettingsCore["settings"]:::service
        UpdaterCore["Updater"]:::service
        BrowserService["BrowserService"]:::service
        PlaywrightService["PlaywrightService"]:::service
        ProxyService["ProxyService"]:::service
        QtEventRunner["QtEventRunner"]:::service
    end
    click Config "https://github.com/houtadono/proxy-wright/blob/main/config.py"
    click Paths "https://github.com/houtadono/proxy-wright/blob/main/core/paths.py"
    click SettingsCore "https://github.com/houtadono/proxy-wright/blob/main/core/settings.py"
    click UpdaterCore "https://github.com/houtadono/proxy-wright/blob/main/core/updater.py"
    click BrowserService "https://github.com/houtadono/proxy-wright/blob/main/services/browser_service.py"
    click PlaywrightService "https://github.com/houtadono/proxy-wright/blob/main/services/playwright_service.py"
    click ProxyService "https://github.com/houtadono/proxy-wright/blob/main/services/proxy_service.py"
    click QtEventRunner "https://github.com/houtadono/proxy-wright/blob/main/services/qt_event_runner.py"

    %% Data Layer
    subgraph "Data Layer"
        DB["Database (SQLite)"]:::data
        Repo["Repository"]:::data
    end
    click DB "https://github.com/houtadono/proxy-wright/blob/main/data/db.py"
    click Repo "https://github.com/houtadono/proxy-wright/blob/main/data/repo.py"

    %% Background Workers
    subgraph "Background Workers"
        BrowserWorker["BrowserWorker"]:::worker
        ProxyCheckWorker["ProxyCheckWorker"]:::worker
        UpdateWorker["UpdateWorker"]:::worker
    end
    click BrowserWorker "https://github.com/houtadono/proxy-wright/blob/main/workers/browser_worker.py"
    click ProxyCheckWorker "https://github.com/houtadono/proxy-wright/blob/main/workers/proxy_check_worker.py"
    click UpdateWorker "https://github.com/houtadono/proxy-wright/blob/main/workers/update_worker.py"

    %% Utilities & Scripts
    subgraph "Utilities & Scripts"
        UpdaterHelper["UpdaterHelper"]:::service
        ReleaseNotes["get_release_notes.py"]:::service
        CleanupQt["cleanup_qt.py"]:::service
    end
    click UpdaterHelper "https://github.com/houtadono/proxy-wright/blob/main/tools/updater_helper.py"
    click ReleaseNotes "https://github.com/houtadono/proxy-wright/blob/main/.github/scripts/get_release_notes.py"
    click CleanupQt "https://github.com/houtadono/proxy-wright/blob/main/.github/scripts/cleanup_qt.py"

    %% External Dependencies
    subgraph "External Dependencies"
        ProxyBinary["3proxy.exe"]:::external
        PlaywrightBrowsers["Playwright Browsers"]:::external
        GitHubAPI["GitHub Releases API"]:::external
    end
    click ProxyBinary "https://github.com/houtadono/proxy-wright/blob/main/bin/3proxy.exe"

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        AppSpec["app.spec"]:::packaging
        UpdaterSpec["updater.spec"]:::packaging
        InstallerISS["installer.iss"]:::packaging
    end
    click AppSpec "https://github.com/houtadono/proxy-wright/blob/main/app.spec"
    click UpdaterSpec "https://github.com/houtadono/proxy-wright/blob/main/updater.spec"
    click InstallerISS "https://github.com/houtadono/proxy-wright/blob/main/installer.iss"

    %% Relationships
    Entrypoint --> MainWindow
    Entrypoint --> Config

    MainWindow -->|opens| ProfileDialog
    MainWindow -->|opens| ProxyDialog
    MainWindow -->|opens| SettingsTab
    MainWindow -->|invoke| BrowserService
    MainWindow -->|invoke| ProxyService
    MainWindow -->|invoke| UpdaterCore

    ProfileDialog -->|load/save| Repo
    SettingsTab -->|load/save| SettingsCore

    BrowserService -->|launch| PlaywrightService
    BrowserService -->|delegate| BrowserWorker
    ProxyService -->|launch| ProxyBinary
    ProxyService -->|delegate| ProxyCheckWorker
    UpdaterCore -->|delegate| UpdateWorker
    UpdaterCore -->|invoke| GitHubAPI

    Repo -->|read/write via| DB

    BrowserWorker -->|status| MainWindow
    ProxyCheckWorker -->|status| MainWindow
    UpdateWorker -->|status| MainWindow

    ServicesGroup(("Core & Services")) -->|uses| UpdaterHelper

    CleanupQt -->|script| Entrypoint
    ReleaseNotes -->|script| Entrypoint

    AppSpec -->|packages| Entrypoint
    UpdaterSpec -->|packages| UpdaterCore
    InstallerISS -->|builds| Entrypoint

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef service fill:#DFFFE0,stroke:#22863A,color:#22863A;
    classDef data fill:#FFE4B5,stroke:#B36200,color:#B36200;
    classDef worker fill:#EAD1DC,stroke:#6F42C1,color:#6F42C1;
    classDef external fill:#F0F0F0,stroke:#586069,color:#586069;
    classDef packaging fill:#FBEFEF,stroke:#C41230,color:#C41230;
```
