Analytics & Win/Loss Heatmaps
Relevant source files
The following files were used as context for generating this wiki page:
The Analytics and Win/Loss Heatmap systems within SweepBot serve as the primary data visualization layer for sweepstakes casino players. These modules provide cross-platform transparency by aggregating session data, Return to Player (RTP) percentages, and temporal patterns into actionable insights. This allows players to track their portfolio performance, streaks, and personal records across multiple platforms in a unified interface.
The system is architected as a React-based frontend that consumes a RESTful Fastify API. The frontend utilizes TanStack Query for data fetching and state management, while the backend performs complex PostgreSQL aggregations to serve downsampled historical data and statistical analysis.
Sources: AGENTS.md, SWEEPBOT_DASHBOARD.html
Analytics Architecture and Data Flow
The Analytics system processes raw transaction and session data to calculate high-level performance metrics. This includes total wagered amounts, net profit/loss, and advanced statistical measures like RTP confidence intervals.
Component Structure
The analytics interface is built using modular React components that display different facets of the player's history:
- Portfolio Overview: Aggregated totals across all platforms, including all-time net and last 7-day performance.
- RTP Analysis: Statistical rigor applied to game payouts, often visualized with confidence intervals.
- Temporal Analysis: Heatmaps showing RTP and performance patterns by hour of the day and day of the week.
Sources: SWEEPBOT_DASHBOARD.html:438-444, AGENTS.md
Data Processing Flow
The following diagram illustrates how user activity is transformed into analytics:
This diagram shows the data request lifecycle from the Analytics UI through the Fastify API to the partitioned PostgreSQL database.
Sources: AGENTS.md, SWEEPBOT_DASHBOARD.html:360-390
Win/Loss Heatmaps and Temporal Tracking
The Heatmap system provides a GitHub-style visualization of daily activity. It allows players to see their performance intensity and consistency over long periods.
Daily P&L Calendar
The heatmap utilizes a grid where each cell represents a day. Colors indicate the intensity of wins or losses for that specific date. The system supports:
- Metric Tracking: Session count, total wagered, total won, and net profit/loss per day.
- Year Navigation: A selector allows users to toggle between different years of activity.
- Detail Tooltips: Hovering over a cell reveals specific day statistics.
Sources: SWEEPBOT_DASHBOARD.html:482-488, QUICK_WINS_CHECKLIST.md:43-44
Streak and Record Management
Complementing the heatmap is the streak tracking engine, which monitors consecutive win or loss days.
- Streaks: Tracking of current and longest streaks. Streaks of 7 or more days trigger a "fire" animation in the UI.
- Personal Records: High-water marks for categories like "Biggest Win," "Longest Streak," and "Best RTP."
Sources: SWEEPBOT_DASHBOARD.html:489-497, SWEEPBOT_DASHBOARD.html:1050-1055
Key API Endpoints and Data Models
The analytics and heatmap features rely on specific endpoints within the /analytics and /features route groups.
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/analytics/portfolio | GET | Returns aggregated totals, per-platform stats, and last 7d performance. |
/features/heatmap | GET | Returns daily P&L data formatted for the calendar grid. |
/features/streaks | GET | Provides current and longest win/loss streak data. |
/features/records | GET | Retrieves personal bests across 7 trophy categories. |
/features/records/refresh | POST | Triggers an idempotent recomputation of records from raw data. |
Sources: SWEEPBOT_DASHBOARD.html:438-440, SWEEPBOT_DASHBOARD.html:482-500
Statistical Metrics
The system emphasizes statistical rigor in its RTP (Return to Player) calculations:
- RTP Calculation: Net Win / Total Wagered, typically computed upon session termination.
- Confidence Intervals: Applied to RTP to provide context on statistical significance.
- Downsampling: Historical data (e.g., 30-day jackpot data) is downsampled hourly to maintain performance.
Sources: SWEEPBOT_DASHBOARD.html:425-427, SWEEPBOT_DASHBOARD.html:451-453
Implementation Details
Frontend Visualization
The frontend utilizes the recharts and Chart.js libraries to render analytical data. Components are wrapped in loading skeletons and empty state handlers to improve perceived performance.
// Example of a loading skeleton pattern for analytics
import { LoadingState } from '../components/ui/loading-state'
if (isLoading) return <LoadingState variant="card" count={3} />
Sources: QUICK_WINS_CHECKLIST.md:21-25, SWEEPBOT_DASHBOARD.html:360-370
Database Considerations
The transactions table is partitioned by month to ensure aggregation queries remain performant as the dataset grows. The Analytics system makes extensive use of Common Table Expressions (CTEs) for multi-faceted portfolio reporting.
Sources: AGENTS.md, SWEEPBOT_DASHBOARD.html:1058-1065
Conclusion
The Analytics & Win/Loss Heatmap system is a critical component of the SweepBot ecosystem, providing players with the cross-platform transparency necessary to manage their sweepstakes portfolio. By combining high-frequency transaction logging with sophisticated PostgreSQL aggregations and interactive React visualizations, SweepBot delivers professional-grade gambling analytics that traditionally favor the house over the player.