Platform Health Checker
Relevant source files
The following files were used as context for generating this wiki page:
The Platform Health Checker is a real-time monitoring service within the SweepBot ecosystem designed to track the availability, response times, and accessibility of various sweepstakes casino platforms. By performing checks every 5 minutes, the service ensures that users are informed of platform outages before attempting to run automations. This data serves as a critical input for the Trust Index, which calculates a platform's trustworthiness based on uptime and performance trends.
Beyond user-facing alerts, the Health Checker provides early warnings of degraded performance, allowing the system to block automation attempts when a platform is unreachable. This prevents failed execution cycles and improves overall system reliability. The service is architected to run as a Python-based background worker, typically deployed on infrastructure like Replit or Railway.
Sources: [services/health-checker/README.md:1-12](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L1-L12), [CLAUDE.md:29-41](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/CLAUDE.md#L29-L41)
System Architecture and Data Flow
The Health Checker operates as an independent service that interacts with the central PostgreSQL database via Supabase. It follows a cyclical execution pattern to fetch platform configurations, perform HTTP requests against multiple endpoints, and persist the results for historical analysis and real-time dashboarding.
Monitoring Lifecycle
The diagram shows the logic performed every 5 minutes by the checker to determine platform health and trigger alerts.
Sources: [services/health-checker/README.md:46-62](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L46-L62)
Service Interaction
The service integrates with the broader SweepBot infrastructure to gate automation and provide visual feedback to users through the web dashboard.
The sequence diagram illustrates how health data flows from the background checker to the end-user interface.
Sources: [services/health-checker/README.md:144-165](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L144-L165), [AGENTS.md:52-65](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/AGENTS.md#L52-L65)
Data Model
The system utilizes two primary tables to track health history and manage active notifications regarding platform status.
Platform Health Checks
This table records every individual check performed by the service, enabling uptime calculation and trend analysis.
| Field | Type | Description |
|---|---|---|
id | UUID | Primary key. |
platform_id | UUID | Foreign key referencing the platforms table. |
status | TEXT | Enumeration: healthy, degraded, down, error. |
avg_response_time_ms | DECIMAL | Average latency across checked URLs. |
endpoint_results | JSONB | Detailed results (status codes/errors) per URL. |
checked_at | TIMESTAMP | Time the check was executed. |
Sources: [services/health-checker/README.md:21-34](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L21-L34)
Platform Alerts
Reused from the ToS Monitor, this table stores actionable alerts when a platform transitions to a 'down' state.
| Field | Type | Description |
|---|---|---|
platform_id | UUID | Affected platform. |
alert_type | TEXT | Set to health_outage or similar. |
severity | TEXT | low, medium, high, critical. |
title | TEXT | Summary of the outage. |
Sources: [services/health-checker/README.md:41-43](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L41-L43), [services/tos-monitor/README.md:41-55](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/tos-monitor/README.md#L41-L55)
Logic and Status Determination
The service evaluates platform health based on HTTP status codes and response latencies. The logic is designed to differentiate between a total outage and minor performance degradation.
- Healthy: All endpoints return 200 OK; average response time is under 3000ms.
- Degraded: Endpoints return 200 OK but are slow (>3s), or some 4xx client errors are present.
- Down: The service encounters a timeout, connection refusal, or 5xx server errors.
- Error: An unexpected exception occurs within the checker script itself.
Sources: [services/health-checker/README.md:52-57](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L52-L57)
Integration with Flow Executor
The FlowExecutor package utilizes health data to perform a "pre-flight" check before running automations. If a platform's latest status is down, the executor throws an error to prevent inconsistent automation states.
// Logic derived from integration guidelines
if (latestCheck.status === 'down') {
throw new Error('Platform is currently unreachable');
}
Sources: [services/health-checker/README.md:120-142](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L120-L142), [packages/flows/src/validator/responsible-play-validator.ts](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/packages/flows/src/validator/responsible-play-validator.ts) (referenced)
Configuration and Deployment
The Health Checker is configured via a PLATFORMS array in the core checker.py script. Each entry defines the URLs to be monitored and specific timeout requirements.
Configuration Schema
{
'slug': 'platform-name',
'name': 'Platform Display Name',
'urls': {
'homepage': 'https://...',
'login': 'https://.../login',
'api': 'https://api...' # Optional
},
'expected_status': 200,
'timeout': 10 # Seconds
}
Sources: [services/health-checker/README.md:73-84](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L73-L84)
Environment Variables
The service requires connection to the Supabase backend.
SUPABASE_URL: The project URL for database interaction.SUPABASE_SERVICE_ROLE_KEY: Service-level key for bypass of Row Level Security (RLS) when writing system-level health logs.
Sources: [services/health-checker/README.md:14-19](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L14-L19), [CLAUDE.md:118-125](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/CLAUDE.md#L118-L125)
Analytics and Monitoring Queries
The Health Checker provides the data necessary for advanced platform reliability metrics. Developers and administrators can use SQL queries to derive uptime percentages and detect patterns in platform instability.
Uptime Percentage Calculation
The following logic is used to calculate 24-hour uptime for the Trust Index:
SELECT
p.name,
ROUND(
(COUNT(CASE WHEN phc.status IN ('healthy', 'degraded') THEN 1 END)::DECIMAL / COUNT(*)) * 100,
2
) as uptime_percentage
FROM platform_health_checks phc
JOIN platforms p ON p.id = phc.platform_id
WHERE phc.checked_at > NOW() - INTERVAL '24 hours'
GROUP BY p.name;
Sources: [services/health-checker/README.md:98-111](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L98-L111), [SWEEPBOT_DASHBOARD.html:1050-1070](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/SWEEPBOT_DASHBOARD.html#L1050-L1070)
Conclusion
The Platform Health Checker is a foundational component of the SweepBot "Data Moat," providing real-time intelligence that differentiates the platform from standard trackers. By integrating health data directly into the automation pipeline and the user's Trust Index, the system ensures high transparency and operational safety for all automated activities.
Sources: [services/health-checker/README.md:167-175](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/services/health-checker/README.md#L167-L175), [AGENTS.md:175-185](https://github.com/VpkDevs/casino-analytics-terminal-6/blob/HEAD/AGENTS.md#L175-L185)