How salarcode/smartproxy works
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.