Fastify API Routes

Relevant source files

The following files were used as context for generating this wiki page:

• SWEEPBOT_DASHBOARD.html
• AGENTS.md
• README.md
• CLAUDE.md
• CODEBASE_IMPROVEMENTS.md
• QUICK_REFERENCE.md

The Fastify API serves as the central backend for the SweepBot ecosystem, facilitating communication between the browser extension, the React dashboard, and the PostgreSQL database. Built with Fastify v5 and TypeScript, it handles critical tasks such as session management, real-time jackpot tracking, automated flows, and payment processing via Stripe.

The API is designed with a focus on strict type safety using Zod for input validation and Drizzle ORM for database interactions. It implements a standard response format across all endpoints to ensure consistency for client-side consumption.

Sources: AGENTS.md, CLAUDE.md, README.md

API Architecture and Middlewares

The API layer is structured to provide secure, validated, and performant access to the SweepBot data layer. It utilizes a variety of Fastify plugins and custom hooks to manage the request lifecycle.

Request Lifecycle and Middleware

Every request to a protected route passes through a requireAuth hook, which verifies the JWT token via Supabase Auth and attaches the user's profile information (ID, email, and subscription tier) to the request object.

Key Global Plugins

Plugin	Purpose	Implementation Detail
@fastify/rate-limit	Traffic control	Configured for 200 req/min (currently in-memory, Redis planned).
@fastify/swagger	Documentation	Auto-generates OpenAPI documentation from Zod schemas.
@fastify/helmet	Security	Adds essential security headers to responses.
@fastify/cors	Access Control	Manages cross-origin requests from the web dashboard and extension.

Sources: SWEEPBOT_DASHBOARD.html:437-463, CODEBASE_IMPROVEMENTS.md

Core Route Modules

The API is divided into functional route modules, each registered as a Fastify plugin.

Session and Transaction Routes

These routes handle the core telemetry data from the browser extension. They manage the lifecycle of a play session and allow for batch insertion of transactions to minimize network overhead.

• POST /sessions: Initializes a new tracking session.
• PATCH /sessions/:id: Ends a session and triggers automatic RTP computation.
• POST /sessions/transactions/batch: Accepts up to 500 transactions in a single call, updating session totals in O(1).

Sources: SWEEPBOT_DASHBOARD.html:565-575, AGENTS.md

Platform and Trust Index Routes

These routes provide data on sweepstakes casinos, including crowdsourced trust signals and Terms of Service (TOS) tracking.

• GET /platforms: Returns a paginated list of platforms with search and status filters.
• GET /platforms/:id/games: Lists games for a specific platform with volatility and RTP data.
• GET /trust-index: Provides rankings based on a 7-factor proprietary scoring algorithm.

Sources: SWEEPBOT_DASHBOARD.html:553-564, AGENTS.md

Flow Automation Routes

The flows module interfaces with the @sweepbot/flows package to interpret natural language and execute automation scripts.

• POST /flows/interpret: Converts a plain English string into a FlowDefinition AST.
• POST /flows/:id/execute: Triggers the asynchronous execution of a defined flow.
• POST /flows/converse: A multi-turn conversation endpoint for building flows (currently a stub).

Sources: SWEEPBOT_DASHBOARD.html:619-626, AGENTS.md, CLAUDE.md

Data Integrity and Validation

All API inputs are strictly validated using Zod schemas before being processed by route handlers. This ensures contract enforcement between the frontend and backend and prevents database errors.

Standard Response Format

To simplify client-side logic, the API adheres to a strict JSON response structure:

Status	Format
Success (Single)	{ "success": true, "data": T }
Success (List)	{ "success": true, "data": T[], "meta": PaginationMeta }
Error	{ "error": string, "message": string, "status": number }

Sources: AGENTS.md, CLAUDE.md

Database Integration

The API uses Drizzle ORM to interact with PostgreSQL. For performance-critical paths, it utilizes optimized patterns such as cachedQuery for Redis caching and transaction wrappers for atomic operations.

Implementation Status and Technical Debt

While the core routing infrastructure is complete, several areas are identified for pre-launch refinement:

• Email Delivery: The system lacks an implementation for sending transactional emails via Resend, despite keys being present in configuration.
• Real-time Updates: WebSocket support for live jackpot updates is currently commented out, with the system relying on 15-second polling.
• Stripe Webhooks: Signature verification and subscription synchronization require hardening to prevent tier drift.
• Distributed Rate Limiting: The current implementation is in-memory, requiring a transition to Redis for multi-instance deployments.

Sources: SWEEPBOT_DASHBOARD.html:516-532, CODEBASE_IMPROVEMENTS.md

The Fastify API routes constitute the backbone of the SweepBot system, providing the necessary endpoints for data ingestion and user interaction. By leveraging Fastify's high-performance architecture and strict TypeScript validation, the system maintains a robust foundation for its Phase 2 expansion into active browser automation.