Getting Started & Setup

Relevant source files

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

• README.md
• CLAUDE.md
• AGENTS.md
• AGENT_QUICK_START.md
• SWEEPBOT_DASHBOARD.html
• AGENT_COORDINATION.md

SweepBot is an integrated ecosystem designed for sweepstakes casino players, providing a "Natural Language Processing (NLP) Flow Engine" for automation, cross-platform transparency, and data intelligence. The project is structured as a TypeScript monorepo using pnpm workspaces and Turborepo to manage multiple applications, including a React dashboard, a Fastify API, and a browser extension.

The setup process involves configuring a local development environment that connects to several external services, including Supabase for database and authentication, Stripe for payments, and Upstash for Redis-based caching and job queues. This guide outlines the prerequisites, installation steps, and architectural overview necessary to begin development.

Sources: README.md:1-12, README.md:42-53, AGENTS.md:7-14

System Prerequisites

Before setting up the project, ensure your environment meets the following technical requirements:

Requirement	Version	Description
Node.js	22+	Required for running the applications and packages.
pnpm	9+	The primary package manager and workspace orchestrator.
Docker	Latest	Necessary for running a local database environment.
TypeScript	5.5	The language used across the entire monorepo.

Sources: README.md:58-61, AGENTS.md:46

Initial Installation & Configuration

The setup follows a standard monorepo workflow. Developers must clone the repository, install dependencies, and configure environment variables.

1. Clone & Install

git clone https://github.com/apPYness/sweepbot.git
cd sweepbot
pnpm install

Sources: README.md:65-68

2. Environment Configuration

The project relies on a .env file for sensitive credentials. A template is provided in .env.example. Key services that must be configured include:

• Supabase: Provides PostgreSQL 16, Auth (JWT), and Storage.
• Stripe: Manages subscription billing and checkout sessions.
• Upstash Redis: Used for caching, rate limiting, and job queues (BullMQ).
• Resend: Handles transactional email delivery.

Sources: README.md:70-73, README.md:113-119, AGENTS.md:105-111

Development Workflow

SweepBot uses pnpm filters to manage the different applications within the monorepo.

Starting Development Servers

To start all applications simultaneously in development mode:

pnpm dev

To run individual applications or packages:

# Start the API (Fastify)
pnpm --filter @sweepbot/api dev

# Start the Web Dashboard (React)
pnpm --filter @sweepbot/web dev

# Start the Browser Extension (WXT)
pnpm --filter @sweepbot/extension dev

Sources: README.md:77-83, CLAUDE.md:15-18

Build & Quality Control

pnpm build        # Build all apps/packages in dependency order
pnpm typecheck    # Run strict TypeScript checking across all packages
pnpm lint         # Run ESLint (0 warnings policy)
pnpm test         # Run all Vitest test suites

Sources: CLAUDE.md:21-30, README.md:130-141

Architectural Overview

The SweepBot monorepo is divided into apps/ and packages/. The following diagram illustrates how these components interact and the technologies supporting each layer.

The architecture leverages a centralized API that coordinates requests from both the Web SPA and the Browser Extension, utilizing shared types and utility packages to maintain consistency.

Sources: SWEEPBOT_DASHBOARD.html:438-472, README.md:42-53, AGENTS.md:21-33

Monorepo Components

Path	Name	Purpose
apps/web	Web Dashboard	React 18 SPA using Vite, Tailwind, and TanStack Router.
apps/api	REST/WS API	Fastify 5 server with Drizzle ORM and PostgreSQL.
apps/extension	Extension	Browser extension built with WXT (MV3).
packages/flows	NLP Engine	core NLP logic for interpreting user automation commands.
packages/types	Shared Types	Canonical Zod schemas and TypeScript interfaces.
packages/utils	Utils	Shared logic for math, dates, and validation.

Sources: README.md:42-53, CLAUDE.md:38-51

Database & Data Moat Setup

The database layer is managed through Drizzle ORM. Before the application is fully functional, migrations and data collection services must be initialized.

1. Migrations: Schemas are defined in apps/api/src/db/schema/. Use pnpm db:migrate to push changes to Supabase.
2. External Services: Python-based services (Jackpot Poller, ToS Monitor, Health Checker) are intended for deployment on Replit to feed data into the PostgreSQL instance.
3. Partitioning: High-volume tables like transactions and jackpot_snapshots are partitioned by month and quarter respectively for performance.

Sources: DATABASE_LAYER_COMPLETE.md:7-14, CLAUDE.md:95-99, AGENTS.md:100-103

Development Coordination

Development is structured around a 4-agent coordination system to prevent domain overlap. Each "Agent" owns a specific territory within the monorepo:

• Agent 1 (Backend): Owns apps/api/ and services/.
• Agent 2 (Frontend): Owns apps/web/.
• Agent 3 (Extension & Shared): Owns apps/extension/ and all packages/.
• Agent 4 (DevOps & Docs): Owns .github/, docs/, and packages/flows/.

Sources: AGENT_COORDINATION.md:9-15, AGENT_QUICK_START.md:15-30

Conclusion

Setting up SweepBot requires a Node.js 22 environment and the configuration of specific cloud services (Supabase, Stripe, and Upstash). By following the monorepo structure and using the provided pnpm scripts, developers can maintain a consistent development experience across the API, web dashboard, and browser extension layers. Ensure environment variables are validated at startup to prevent runtime failures in critical service integrations.

Sources: README.md:149-153, CLAUDE.md:120-125, AGENT_COORDINATION.md:139-144