TOS Monitor Service
Relevant source files
The following files were used as context for generating this wiki page:
The TOS Monitor Service is a critical compliance and transparency component of the SweepBot ecosystem. Its primary purpose is to track daily changes to the Terms of Service (ToS) of various sweepstakes casino platforms, alerting users to modifications that could impact their play, such as changes to withdrawal limits, wagering requirements, or redemption policies. By maintaining a historical record of these documents, the service provides data for the project's Trust Index and offers legal protection through historical documentation that cannot be reconstructed after the fact.
Sources: services/tos-monitor/README.md:3-12, services/tos-monitor/monitor.py:1-6
System Architecture
The service operates as an independent Python-based microservice, typically deployed on infrastructure like Replit or Railway, and interacts with the centralized Supabase database. It consists of a backend scraper and monitoring logic paired with a React-based frontend dashboard for user visibility.
High-Level Component Flow
The following diagram illustrates the lifecycle of a ToS check, from fetching content to alerting the user.
Core Backend Logic
The backend service is implemented in Python and utilizes BeautifulSoup for HTML parsing and difflib for generating text differences.
Monitoring Workflow
- Fetching: The service uses a list of platform configurations including a
slug,tos_url, and a CSScontent_selectorto locate the main text within the platform's ToS page. - Comparison: It retrieves the latest snapshot from the
tos_snapshotstable. If the SHA-256 hash of the new content differs from the previous record, a change is detected. - Analysis: The
detect_changesfunction generates a unified diff and counts additions and removals. It specifically scans these changes for a pre-defined list ofIMPORTANT_KEYWORDS.
Sources: services/tos-monitor/monitor.py:38-76, services/tos-monitor/monitor.py:121-150
Important Keywords
The service prioritizes changes containing specific terms that affect player equity:
| Category | Keywords |
|---|---|
| Financial | withdrawal, redeem, redemption, payout, cashout |
| Requirements | wagering, playthrough, requirement, bonus |
| Account/Legal | verification, kyc, terminate, suspend, ban, dispute, arbitration |
| Sweepstakes | sweep, promotional, coins |
Sources: services/tos-monitor/monitor.py:78-87, services/tos-monitor/README.md:76-81
Data Models
The service relies on two primary tables within the Supabase PostgreSQL database to store historical data and user-facing alerts.
TOS Snapshots Table
Stores the raw content and metadata for every detected change.
| Field | Type | Description |
|---|---|---|
id | UUID | Primary Key |
platform_id | UUID | Foreign Key to platforms |
content | TEXT | The full extracted text of the ToS |
content_hash | TEXT | SHA-256 hash for quick comparison |
change_detected | BOOLEAN | Flag set to true if content changed from last scan |
change_summary | JSONB | Contains counts of additions/removals and detected keywords |
captured_at | TIMESTAMPTZ | Timestamp of the scan |
Sources: services/tos-monitor/README.md:21-34, services/tos-monitor/monitor.py:155-165
Platform Alerts Table
Generated when significant changes are detected to be displayed in the web dashboard.
| Field | Type | Description |
|---|---|---|
severity | TEXT | 'low', 'medium', 'high', or 'critical' |
alert_type | TEXT | Set to 'tos_change' |
metadata | JSONB | Contains the specific keywords and diff summary |
Sources: services/tos-monitor/README.md:36-44, services/tos-monitor/monitor.py:182-195
Frontend Implementation
The frontend is a React component (TosMonitorPage.tsx) that provides a user-friendly interface for reviewing ToS changes. It features a "Spotlight" UI for major alerts and a timeline of recent activity.
Feature Matrix
- Live Indicator: Shows the status of the monitoring service and the time of the last scan.
- Severity Badges: Categorizes changes as Major, Moderate, Minor, or Info based on keyword density and impact.
- Diff Previewer: An inline monochromatic diff viewer that highlights added lines in green and removed lines in red.
- Watchlist: Allows users to toggle notifications for specific platforms.
Sources: apps/web/src/pages/TosMonitorPage.tsx:189-201, apps/web/src/pages/TosMonitorPage.tsx:216-247, apps/web/src/pages/TosMonitorPage.tsx:325-364
User Notification Flow
When a major change is detected, the system integrates with the NotificationPanel and email-service.ts to alert affected users.
Trust Index Integration
The TOS Monitor Service is a primary data provider for the SweepBot Trust Index, a proprietary scoring algorithm. The "TOS Stability" factor (weighted at 15% of the total score) penalizes platforms that frequently modify their terms, especially if those changes involve major financial or eligibility restrictions. Fewer changes result in a higher stability score, which is surfaced to users in the platform discovery pages.
Sources: services/tos-monitor/README.md:13-14, SWEEPBOT_DASHBOARD.html:1388-1390, apps/web/src/pages/TosMonitorPage.tsx:645-655
Conclusion
The TOS Monitor Service serves as an automated watchdog within the SweepBot platform. By combining automated web scraping, cryptographic hash comparison, and keyword-based risk assessment, it transforms complex legal documents into actionable intelligence for players. Its integration into the Trust Index and the notification subsystem ensures that users remain informed of platform policy shifts in real-time.
Sources: services/tos-monitor/README.md:143-148, services/tos-monitor/monitor.py:1-6