Browser Extension Fundamentals
Relevant source files
The following files were used as context for generating this wiki page:
The SweepBot browser extension serves as a critical bridge between the user's casino gameplay and the centralized analytics platform. Its primary purpose is to provide passive session tracking, transaction capture, and real-time data intelligence directly within the browser environment. By intercepting network requests on supported sweepstakes casino sites, the extension automates the collection of wagering data, which is then processed to provide cross-platform transparency.
As a core component of the SweepBot ecosystem, the extension works in tandem with the Web Dashboard and the API Layer. It is built using the WXT framework to support modern browser standards while ensuring compatibility across Chrome and Firefox. Sources: README.md, AGENTS.md, CLAUDE.md
Architectural Overview
The extension architecture is built on Manifest V3 (MV3) and utilizes the WXT (Web Extension Tools) framework for build orchestration and cross-browser support. The system is divided into several specialized contexts that handle distinct responsibilities, ranging from background processing to DOM manipulation.
Core Components and Contexts
The extension logic is distributed across three primary execution environments:
- Background Service Worker: The central orchestrator handling long-running tasks, message routing, and API communication.
- Content Scripts: Scripts injected into casino websites to perform DOM manipulation and intercept network traffic (XHR/Fetch).
- Popup UI: A React-based interface providing users with immediate controls and status updates.
Sources: AGENT_3_EXTENSION_SHARED.md, AGENTS.md, CLAUDE.md
Extension Lifecycle and Data Flow
The following diagram illustrates how the extension intercepts data from a casino platform and relays it to the SweepBot API.
The extension extracts {bet, win, balance} data from intercepted requests and batches them to the POST /transactions/batch endpoint. Sources: CLAUDE.md, AGENTS.md
Key Subsystems
Detection and Interception Engine
The extension includes a detection engine capable of identifying over 10 different casino platforms. It uses specialized interceptors to monkey-patch XHR and Fetch requests, allowing it to capture transaction data without requiring manual user input.
Sources: AGENTS.md, AGENT_3_EXTENSION_SHARED.md
Real-Time RTP Calculation
Integrated within the extension is an RTP (Return to Player) calculator that performs real-time volatility and return calculations based on captured session data. This allows users to see their performance metrics instantly as they play.
Sources: AGENTS.md, CLAUDE.md
Type-Safe Storage and API Layer
The extension utilizes a type-safe wrapper for Chrome Storage to manage local state and session data. It also communicates with the central API via a dedicated client that handles authentication and automatic retry logic with exponential backoff.
Sources: AGENT_3_EXTENSION_SHARED.md, AGENTS.md
Configuration and Implementation
The extension is configured via wxt.config.ts, which defines the manifest requirements and build settings. It is strictly Manifest V3 compliant to ensure longevity and acceptance in the Chrome Web Store.
Extension Feature Matrix
| Feature | Description | Implementation Detail |
|---|---|---|
| Platform Detection | Detects 10+ sweepstakes platforms | src/lib/platforms.ts |
| Transaction Capture | Monkey-patching XHR/Fetch | src/lib/interceptor.ts |
| Affiliate Injection | Referral link and signup tracking | src/lib/affiliate.ts |
| Voice Commands | Voice input for flow commands | src/lib/voice-recorder.ts |
| Session Persistence | Type-safe storage wrapper | src/lib/storage.ts |
Sources: AGENTS.md, AGENT_3_EXTENSION_SHARED.md, SWEEPBOT_DASHBOARD.html
Background Worker Logic
The background worker acts as the persistent heartbeat of the extension. It manages the lifecycle of tracking sessions and ensures that data is successfully transmitted to the API even if the user closes a tab.
Sources: CLAUDE.md, AGENTS.md, SWEEPBOT_DASHBOARD.html
Technical Requirements and Standards
The extension must adhere to several strict quality and compliance standards:
- CSP Compliance: Must strictly follow Content Security Policy requirements with no use of
eval()or dangerous anti-patterns. - Framework: Built using WXT (Web Extension Tools) with a React 18 frontend for the popup.
- Type Safety: Uses shared TypeScript interfaces from
packages/typesto ensure contract consistency with the API. - Performance: Optimized for low memory usage and minimal impact on the host browser's performance.
Sources: AGENT_3_EXTENSION_SHARED.md, AGENTS.md, CLAUDE.md
Conclusion
The SweepBot extension is the primary data acquisition tool for the platform, enabling automated, passive tracking of casino gameplay. Its integration of network interception, real-time math engines, and type-safe API communication makes it a fundamental component in delivering transparency to the sweepstakes casino ecosystem.