# salarcode/smartproxy architecture

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

- Interactive diagram: https://gitdiagram.com/salarcode/smartproxy
- Repository: https://github.com/salarcode/smartproxy

## Overview

##### Project Type and Purpose
- SmartProxy is a cross-browser extension (Chrome, Firefox, Edge, Thunderbird) built on WebExtensions/Chrome Extensions APIs.
- Its purpose is to automatically switch proxy settings for selected websites based on user‐defined rules or subscription lists, without manual intervention.

##### File Structure
- Top-Level Files: package.json, tsconfig.json, webpack.config.js, build scripts, manifests for each browser (manifest-chrome.json, manifest-firefox.json, etc.).
- src/_locales: Localization resources (en, es, ru, zh, etc.).
- src/ui: UI layer – HTML (popup.html, settings.html), CSS, JS for popup and settings pages.
- src/core: Background logic – modular services (ProxyEngine, ProxyRules, ProfileOperations, TabManager, WebRequestMonitor, SubscriptionUpdater, ServiceWorker for MV3).
- src/lib: Shared utilities (events, polyfills, importers, benchmarks).
- wiki folder and CI/CD configs (.travis.yml, crowdin.yml) for documentation and localization workflow.

##### README for Additional Insights
- Highlights dynamic rule patterns, one-click rule creation, subscription support, backup/restore, multi-browser compatibility.
- Build/test instructions show two build targets (MV2 for Chrome, MV3 for Firefox), illustrating that the background logic can run as either a persistent background script or service worker.

a. Main Components
- UI Layer: Popup & Settings pages
- Core Background Service:
– ServiceWorker (MV3) or Background Script (MV2)
– Modules: ProxyEngine (with browser adapters), ProxyRules/ProfileRules, SubscriptionUpdater, SettingsOperation, TabManager & RequestLogger, WebRequestMonitor
- Browser API: webRequest, proxy, storage, runtime messaging
- External Services: Subscription servers (for rule lists), Localization platform (Crowdin)
- Build Pipeline: Webpack, Node.js scripts

b. Relationships & Interactions
- UI → Core: runtime.sendMessage / runtime.onMessage → triggers operations (e.g., add rule, switch profile)
- Core → Browser API:
– webRequest.onBeforeRequest → WebRequestMonitor → ProxyEngine determines if the request should be proxied
– proxy.settings.set → apply proxy rules
– storage API → persist settings and rule lists
- Core ↔ External Services: SubscriptionUpdater polls subscription endpoints to refresh rule lists
- ServiceWorker Lifecycle: start background modules on install/activate events

c. Architectural Patterns & Design Principles
- Event-Driven / Observer Pattern (LiteEvent) – modules subscribe to browser events
- Adapter Pattern – ProxyEngineChrome, ProxyEngineFirefox, etc. isolate browser-specific logic
- Modular Single Responsibility – each core class (Settings, ProfileOperations, WebFailedRequestMonitor) handles one concern

d. Key Technologies & Frameworks
- TypeScript (strong typing, interfaces)
- WebExtensions API (browser-independent proxy, webRequest, messaging)
- Webpack for bundling multi-target artifacts (MV2 vs MV3)
- Node.js build scripts (npm tasks, PowerShell for packaging)
- Crowdin for localization

##### Diagramming Conventions
- Components:
- Rounded rectangles for UI components
- Rectangles for background modules/services
- Clouds for browser APIs and external services
- UI (blue), Core (green), Browser API (gray), External (orange)

##### Detailed Capture of Architectural Elements
- Manifest files as entry points per browser (highlight MV2 vs MV3).
- How localization files feed into the UI at build time.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build Pipeline"
        WP["Webpack Config"]:::build
        BS["Build Scripts"]:::build
    end

    subgraph "UI Layer"
        PP["Popup Page"]:::ui
        SP["Settings Page"]:::ui
        ProxP["Proxyable Page"]:::ui
        LOC["Localization Resources"]:::ui
    end

    subgraph "Core Background Service"
        CE["Core Entry Point"]:::core
        SW["ServiceWorker (MV3)"]:::core
        BG["Background Script (MV2)"]:::core
        ProxyE["ProxyEngine Core"]:::core
        PEChrome["ProxyEngineChrome"]:::core
        PEFF["ProxyEngineFirefox"]:::core
        PESR["ProxyEngineSpecialRequests"]:::core
        PR["ProxyRules & ProfileRules"]:::core
        PO["Profile Operations"]:::core
        SU["Subscription Updater"]:::core
        SO["Settings Operations"]:::core
        TM["TabManager & Logger"]:::core
        WRM["WebRequestMonitor"]:::core
        UPM["Update Manager"]:::core
        PA["Proxy Authentication"]:::core
        KS["Keyboard Shortcuts"]:::core
        ICON["Icons Definition"]:::core
    end

    subgraph "Browser APIs"
        WEBREQ["webRequest API"]:::api
        PROXYAPI["proxy API"]:::api
        STORAGE["storage API"]:::api
        RUNTIME["runtime messaging"]:::api
    end

    subgraph "External Services"
        SUBS["Subscription Servers"]:::external
        CROWDIN["Localization Platform"]:::external
    end

    WP -->|bundles| PP
    WP -->|bundles| SP
    WP -->|bundles| ProxP
    WP -->|bundles| SW
    WP -->|bundles| BG
    BS -->|invokes| WP

    PP -->|runtime.sendMessage| RUNTIME
    SP -->|runtime.sendMessage| RUNTIME
    ProxP -->|runtime.sendMessage| RUNTIME
    RUNTIME -->|onMessage| CE

    CE --> ProxyE
    CE --> PR
    CE --> PO
    CE --> SU
    CE --> SO
    CE --> TM
    CE --> WRM
    CE --> UPM
    CE --> PA
    CE --> KS
    CE --> ICON

    WEBREQ -->|onBeforeRequest| WRM
    WRM -->|evaluate| ProxyE
    ProxyE -->|use| PROXYAPI
    SU -.->|polls| SUBS
    LOC -.->|sourced from| CROWDIN

    click PP "https://github.com/salarcode/smartproxy/blob/master/src/ui/popup.html"
    click SP "https://github.com/salarcode/smartproxy/blob/master/src/ui/settings.html"
    click ProxP "https://github.com/salarcode/smartproxy/blob/master/src/ui/proxyable.html"
    click LOC "https://github.com/salarcode/smartproxy/tree/master/src/_locales"
    click CE "https://github.com/salarcode/smartproxy/blob/master/src/core/Core.ts"
    click SW "https://github.com/salarcode/smartproxy/blob/master/src/core/ServiceWorker/CoreServiceWorker.ts"
    click BG "https://github.com/salarcode/smartproxy/blob/master/src/core/Core.ts"
    click ProxyE "https://github.com/salarcode/smartproxy/blob/master/src/core/ProxyEngine.ts"
    click PEChrome "https://github.com/salarcode/smartproxy/blob/master/src/core/ProxyEngineChrome.ts"
    click PEFF "https://github.com/salarcode/smartproxy/blob/master/src/core/ProxyEngineFirefox.ts"
    click PESR "https://github.com/salarcode/smartproxy/blob/master/src/core/ProxyEngineSpecialRequests.ts"
    click PR "https://github.com/salarcode/smartproxy/blob/master/src/core/ProxyRules.ts"
    click PO "https://github.com/salarcode/smartproxy/blob/master/src/core/ProfileOperations.ts"
    click SU "https://github.com/salarcode/smartproxy/blob/master/src/core/SubscriptionUpdater.ts"
    click SO "https://github.com/salarcode/smartproxy/blob/master/src/core/SettingsOperation.ts"
    click TM "https://github.com/salarcode/smartproxy/blob/master/src/core/TabManager.ts"
    click WRM "https://github.com/salarcode/smartproxy/blob/master/src/core/WebRequestMonitor.ts"
    click UPM "https://github.com/salarcode/smartproxy/blob/master/src/core/UpdateManager.ts"
    click PA "https://github.com/salarcode/smartproxy/blob/master/src/core/ProxyAuthentication.ts"
    click KS "https://github.com/salarcode/smartproxy/blob/master/src/core/KeyboardShortcuts.ts"
    click ICON "https://github.com/salarcode/smartproxy/blob/master/src/core/Icons.ts"
    click WP "https://github.com/salarcode/smartproxy/blob/master/webpack.config.js"
    click BS "https://github.com/salarcode/smartproxy/blob/master/build-and-pack.ps1"

    classDef ui fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef core fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef api fill:#E0E0E0,stroke:#424242,color:#424242
    classDef external fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef build fill:#E1BEE7,stroke:#6A1B9A,color:#6A1B9A
```
