Monorepo Architecture
Relevant source files
The following files were used as context for generating this wiki page:
SweepBot is architected as a modern TypeScript monorepo utilizing pnpm workspaces and Turborepo for build orchestration and dependency management. This structure enables the project to maintain distinct applications for the web dashboard, API, and browser extension while sharing critical logic, types, and configurations through internal packages.
The architecture follows a modular approach where the backend, frontend, and extension layers are decoupled but unified through a shared type system and utility library. This ensures consistency across the ecosystem, particularly for complex logic like the NLP automation engine and statistical RTP (Return to Player) calculations.
Sources: AGENTS.md:36-47, CLAUDE.md:29-41, README.md:34-45
Workspace Structure
The repository is organized into two primary directories: apps/ for deployable services and packages/ for shared internal libraries.
Core Applications (apps/)
These represent the entry points of the SweepBot ecosystem.
| Application | Technology Stack | Description |
|---|---|---|
web | React 18, Vite, TanStack Router, Tailwind CSS | The central player dashboard for portfolio visibility and analytics. |
api | Fastify 5, TypeScript, Drizzle ORM | REST and WebSocket API handling business logic and DB interactions. |
extension | WXT, React, MV3 | Browser extension for passive session tracking and site interception. |
Shared Packages (packages/)
Internal libraries used across multiple applications to prevent code duplication.
| Package | Purpose | Key Contents |
|---|---|---|
flows | NLP Automation Engine | Interpreter, Executor, and Scheduler for user-defined tasks. |
types | Shared Schema & Interfaces | Zod schemas and TypeScript interfaces for API contracts. |
utils | Common Utilities | Math, logging, validation, and crypto helpers. |
config | Tooling Configuration | Shared ESLint, TypeScript, and Tailwind configurations. |
Sources: AGENTS.md:38-47, README.md:36-44, CLAUDE.md:30-41
System Topology and Data Flow
The SweepBot ecosystem operates through a centralized API that mediates communication between the data layer and various client interfaces. The browser extension acts as a data collector, while the web dashboard serves as the primary consumption layer for analytics.
The diagram shows the high-level interaction between the client applications and the backend infrastructure.
Sources: AGENTS.md:52-81, SWEEPBOT_DASHBOARD.html:246-275, CLAUDE.md:43-52
Data Modeling and Persistence
Persistence is handled by PostgreSQL 16 via Supabase, with Drizzle ORM serving as the type-safe interface. A critical architectural decision involves data partitioning for high-volume tables:
transactionstable is partitioned by month.jackpot_snapshotstable is partitioned by quarter.
Entity Relationship Model
The ER diagram illustrates the core relationships between users (profiles), their gameplay data, and the automation engine.
Sources: AGENTS.md:121-130, SWEEPBOT_DASHBOARD.html:277-295, CLAUDE.md:76-80
NLP Automation Engine Pipeline
The packages/flows directory contains the most complex logic in the monorepo, responsible for turning natural language into executable scripts. It follows a multi-pass interpretation pipeline.
This sequence diagram tracks the lifecycle of an automation command from raw text to execution.
Sources: AGENTS.md:95-104, CLAUDE.md:54-58, README.md:25-32
Build and Developer Experience (DX)
The monorepo leverages Turborepo to optimize build times through caching and parallel execution. Configuration is centralized in the root of the project to ensure consistency across workspaces.
Key Build Commands
| Command | Action | Scope |
|---|---|---|
pnpm dev | Starts all apps | Root |
pnpm build | Builds all apps/packages | Root |
pnpm test | Runs Vitest suites | Root/Package |
pnpm db:migrate | Pushes schema changes | apps/api |
Environment Validation
To prevent runtime failures, the monorepo implements a strict environment validation pattern using Zod. The API and Web apps utilize env.ts files that parse and validate process.env at startup, ensuring that critical secrets like STRIPE_SECRET_KEY or DATABASE_URL are present and correctly formatted.
Sources: CLAUDE.md:12-27, CODEBASE_IMPROVEMENTS.md:70-85, AGENTS.md:132-143
Multi-Agent Coordination Protocol
The repository includes a specific protocol for multi-agent development, assigning exclusive domain ownership to different technical roles to prevent merge conflicts.
- Agent 1 (Backend): Owns
apps/api/andservices/. - Agent 2 (Frontend): Owns
apps/web/. - Agent 3 (Extension/Shared): Owns
apps/extension/andpackages/types|utils. - Agent 4 (DevOps/Docs): Owns
docs/,packages/flows/, and CI/CD.
Sources: AGENT_COORDINATION.md:10-45, README_AGENTS.md:13-45
Conclusion
The SweepBot monorepo architecture is designed for high-performance data processing and rapid feature iteration. By centralizing core logic in shared packages and utilizing strict type-safe contracts between the backend and various clients, the system maintains a high bar for code quality and reliability, particularly in the critical areas of transaction tracking and responsible play automation.