Introduction to SweepBot
Relevant source files
The following files were used as context for generating this wiki page:
SweepBot is an all-in-one "operating system" designed for the sweepstakes casino player ecosystem. It provides cross-platform transparency, task automation, and data-driven intelligence to help players manage their activity across various virtual currency platforms. The system is architected as a monorepo containing a web dashboard, a REST/WebSocket API, a browser extension, and a specialized natural language processing (NLP) automation engine. Sources: README.md:3-8, AGENTS.md:5-10, CLAUDE.md:5-8
The project focuses on three primary value propositions: automation of tedious tasks (such as daily bonus collection), crowdsourced intelligence for platform trust and jackpot tracking, and comprehensive portfolio visibility. Notably, SweepBot is a productivity and transparency tool rather than a gambling product, operating within the legal framework of sweepstakes law. Sources: README.md:12-14, AGENTS.md:30-33, CLAUDE.md:5-9
System Architecture
SweepBot utilizes a modern monorepo structure managed by pnpm and Turborepo. The architecture is split into several distinct layers that handle user interface, business logic, data persistence, and specialized automation. Sources: README.md:23-35, AGENTS.md:18-28, CLAUDE.md:46-60
Monorepo Components
| Component | Path | Technology Stack | Description |
|---|---|---|---|
| Web Dashboard | apps/web/ | React 18, TanStack Router, Tailwind CSS | A SPA providing the primary user interface for data visualization and management. |
| API Server | apps/api/ | Fastify 5, Drizzle ORM, TypeScript | REST and WebSocket API handling business logic and DB communication. |
| Browser Extension | apps/extension/ | WXT, React, MV3 | Intercepts traffic on casino sites to track sessions and calculate RTP. |
| Flows Engine | packages/flows/ | TypeScript, node-cron | A specialized package for NLP interpretation and automation execution. |
| Shared Types | packages/types/ | Zod, TypeScript | Shared interfaces and validation schemas used across the entire monorepo. |
Sources: README.md:37-45, AGENTS.md:37-56, CLAUDE.md:46-60
High-Level Data Flow
The system captures data through the browser extension, which intercepts XHR/Fetch requests on casino platforms. This data is batched and sent to the API, where it is persisted and used for real-time analytics and dashboard rendering. Sources: CLAUDE.md:62-65, AGENTS.md:105-110
Explanation: This diagram shows the data flow from the extension to the backend, including storage in PostgreSQL and Redis, and real-time updates to the web dashboard. Sources: README.md:23-35, CLAUDE.md:62-65
Core Features and Modules
NLP Flows Engine (@sweepbot/flows)
The Flows Engine is a core package that interprets natural language into executable Abstract Syntax Trees (AST). It handles the conversion of user intent (e.g., "Claim my bonus every day at 9 AM") into scheduled automation scripts. Sources: packages/flows/README.md:3-12, README.md:47-60
- Interpretation Pipeline: A 4-pass process consisting of entity extraction, intent classification, AST building, and validation. Sources: packages/flows/README.md:6-8, CLAUDE.md:67-71
- Execution Nodes: The AST uses 9 node types, including
ActionNode,ConditionNode,LoopNode, andSequenceNode. Sources: packages/flows/README.md:204-215, CLAUDE.md:73-74 - Responsible Play Guardrails: Mandatory limits such as
max_duration(default 2 hours) andcool_down_checkare enforced at the engine level to prevent excessive play. Sources: packages/flows/README.md:14-18, AGENTS.md:158-164, CLAUDE.md:99-105
Data Collection and Moat
SweepBot aggregates proprietary data to provide a "Trust Index" and "Community Benchmarks" for redemption speeds. Sources: AGENTS.md:9-12, SWEEPBOT_DASHBOARD.html:125-132
- Trust Index: A 7-factor proprietary scoring algorithm (including redemption speed, rejection rate, and TOS stability) that rates the reliability of sweepstakes platforms. Sources: SWEEPBOT_DASHBOARD.html:562-572
- Jackpot Intelligence: Real-time tracking of jackpot values across multiple platforms via specialized poller services. Sources: DATABASE_LAYER_COMPLETE.md:10-15, AGENTS.md:103-104
- TOS Monitoring: Automated detection of changes in platform Terms of Service, providing plain English alerts to users. Sources: AGENTS.md:12, DATABASE_LAYER_COMPLETE.md:11
Database Schema
The database is built on PostgreSQL 16 (hosted via Supabase) and managed using Drizzle ORM. It employs partitioning for high-volume time-series data. Sources: DATABASE_LAYER_COMPLETE.md:3-35, AGENTS.md:52-54, CLAUDE.md:88-92
Entity Relationship Diagram
Explanation: This ER diagram visualizes the relationships between core entities such as users (profiles), gaming sessions, transactions, and the automation flows. Sources: SWEEPBOT_DASHBOARD.html:437-458, DATABASE_LAYER_COMPLETE.md:55-66
Key Data Tables
| Table | Partitioning | Description |
|---|---|---|
transactions | Monthly | Stores every individual bet, win, and balance change captured by the extension. |
sessions | None | Aggregates transaction data into gameplay sessions for RTP calculation. |
jackpot_snapshots | Quarterly | High-frequency time-series data of jackpot values across platforms. |
tos_snapshots | None | Historical records of platform Terms of Service for change detection. |
redemptions | None | Tracks user payout requests and community-sourced processing times. |
Sources: DATABASE_LAYER_COMPLETE.md:7-15, AGENTS.md:127-130, CLAUDE.md:91-92
Security and Compliance
SweepBot implements a "Zero-Knowledge" design philosophy for sensitive credentials and strictly enforces JWT-based authentication via Supabase. Sources: README.md:79, SECURITY.md:65-75
- Authentication: Uses Supabase Auth with JWT. Tokens are stored only in memory, with refresh tokens kept in
httpOnly, Secure, SameSite=Strictcookies. Sources: SECURITY.md:65-69, AGENTS.md:55 - Data Isolation: PostgreSQL Row Level Security (RLS) is enabled on all user-scoped tables to ensure users can only access their own data. Sources: SECURITY.md:71-74, AGENTS.md:126
- Responsible Play: Non-negotiable guardrails are baked into the
@sweepbot/flowspackage. These include loop safety caps (max 100 iterations) and mandatory cool-down checks that cannot be overridden by the user. Sources: AGENTS.md:158-164, packages/flows/README.md:130-138, CLAUDE.md:99-105
Conclusion
SweepBot represents a comprehensive technical solution for modernizing the player experience in sweepstakes casinos. By combining real-time data interception via the browser extension with a natural language automation engine, the platform creates a powerful "data moat" through crowdsourced intelligence. Its architecture prioritizes security through RLS and ethical usage via embedded "Responsible Play" guardrails. Sources: README.md:12-14, AGENTS.md:166-170, DATABASE_LAYER_COMPLETE.md:85-90