ToRivers

An AI-powered automation marketplace with pay-per-execution billing. Users top-up wallets and pay per execution for AI-powered workflows.

Table of Contents

• Overview
• Architecture
• Tech Stack
• Project Structure
• Prerequisites
• Getting Started
• Available Commands
• Environment Variables
• Development Workflow
• Documentation
• Deployment
• Contributing
• License

Overview

ToRivers is a marketplace platform where users can discover, purchase, and execute AI-powered automations. The platform features:

• Marketplace: Browse and install AI-powered automations
• Wallet System: Pay-per-execution billing with credit top-ups
• Real-time Execution: Live streaming of automation progress via WebSocket
• Credential Management: Secure OAuth and API key storage
• Credential Compatibility Matching: DB-backed provider/scope matching (e.g. one Google credential can satisfy Sheets/Drive/Calendar requirements)
• Multi-agent Workflows: LangGraph-powered orchestration for complex automations

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         ToRivers Architecture                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌────────────────┐                                                      │
│  │  Next.js Web   │  React 19, tRPC, Tailwind CSS                       │
│  │   (Port 3000)  │  User dashboard, marketplace, wallet                │
│  └───────┬────────┘                                                      │
│          │                                                               │
│          │ tRPC (Type-safe API)                                          │
│          ▼                                                               │
│  ┌────────────────┐                                                      │
│  │  tRPC Router   │  Business logic, validation, payments               │
│  │  (@workspace/  │  Stripe integration, credit management              │
│  │     api)       │                                                      │
│  └───────┬────────┘                                                      │
│          │                                                               │
│          │ HTTP POST /execute                                            │
│          ▼                                                               │
│  ┌────────────────┐     ┌────────────────┐                              │
│  │  AI Engine v2  │────▶│     Redis      │  Message broker              │
│  │  FastAPI/8001  │     │                │  Task queue                  │
│  └───────┬────────┘     └───────┬────────┘                              │
│          │                      │                                        │
│          │                      ▼                                        │
│          │              ┌────────────────┐                              │
│          │              │ Celery Workers │  Distributed processing       │
│          │              └───────┬────────┘                              │
│          │                      │                                        │
│          │                      ▼                                        │
│          │              ┌────────────────┐                              │
│          │              │   LangGraph    │  Multi-agent workflows        │
│          │              └───────┬────────┘                              │
│          │                      │                                        │
│          ▼                      ▼                                        │
│  ┌──────────────────────────────────────────┐                           │
│  │           Supabase PostgreSQL             │                           │
│  │    (Single Source of Truth for all data)  │                           │
│  │    RLS, Real-time, pgvector, Auth         │                           │
│  └──────────────────────────────────────────┘                           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology
Frontend	Next.js 15, React 19, TypeScript, Tailwind CSS 4
API	tRPC 11, React Query, Zod validation
Database	Supabase PostgreSQL, pgvector, RLS
Authentication	Supabase Auth (Google OAuth)
Payments	Stripe (wallet top-ups)
AI Engine	Python 3.11+, FastAPI, LangGraph, Celery
Task Queue	Redis, Celery workers
AI Models	OpenAI, Anthropic (via OpenRouter)
Monorepo	Turborepo, pnpm workspaces

Project Structure

torivers-v2/
├── apps/
│   ├── web/                    # Next.js main application (dashboard, marketplace)
│   ├── public/                 # Public-facing landing page
│   ├── ai-engine-v2/           # LangGraph + Celery orchestration (PRIMARY)
│   └── ai-engine/              # Legacy CrewAI service (deprecated)
├── packages/
│   ├── api/                    # tRPC routers and business logic
│   ├── database/               # Supabase client and generated types
│   ├── ui/                     # Shared UI components (Radix, Tailwind)
│   ├── shared/                 # Common utilities and constants
│   └── eslint-config/          # Shared ESLint configuration
├── supabase/
│   ├── migrations/             # Database migrations
│   └── functions/              # Edge functions
├── docs/                       # Project documentation
├── scripts/                    # Build and deployment scripts
├── monitoring/                 # Grafana dashboards
└── tooling/                    # Development tooling

Prerequisites

• Node.js >= 20
• pnpm >= 10.4.1
• Python >= 3.11
• Docker & Docker Compose
• Supabase CLI
• Stripe CLI (for webhook testing)

Getting Started

1. Clone the Repository

git clone <repository-url>
cd torivers-v2

2. Install Dependencies

# Install Node.js dependencies (ALWAYS use pnpm, never npm/yarn)
pnpm install

3. Configure Environment Variables

# Generate a local env file from the unified root template
./scripts/deploy/generate-env.sh --env local --output .env

See Environment Variables section for required values.

4. Set Up Supabase

# Start local Supabase instance
supabase start

# Apply migrations
supabase db push

# Generate TypeScript types
pnpm db:generate-types

5. Set Up AI Engine

cd apps/ai-engine-v2
python3.11 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

6. Start Development Servers

# Terminal 1: Next.js app (managed by you, not by pnpm dev)
cd apps/web && pnpm dev

# Terminal 2: AI Engine (Docker recommended)
cd apps/ai-engine-v2 && docker-compose up -d

# Terminal 3: Stripe webhooks (optional)
stripe listen --forward-to localhost:3000/api/webhooks/stripe

7. Access the Application

Service	URL
Web App	http://localhost:3000
Public Site	http://localhost:3001
AI Engine API	http://localhost:8001
API Docs	http://localhost:8001/docs
Flower Dashboard	http://localhost:5555
Supabase Studio	http://localhost:54323

Available Commands

Root Commands

pnpm install              # Install all dependencies
pnpm build                # Build all packages and apps
pnpm lint                 # Run ESLint across all packages
pnpm type-check           # TypeScript validation
pnpm format               # Prettier formatting
pnpm clean                # Clean build artifacts

Database Commands

pnpm db:push              # Push schema changes to Supabase
pnpm db:reset             # Reset database (WARNING: deletes data)
pnpm db:generate-types    # Regenerate TypeScript types from schema

AI Engine Commands (apps/ai-engine-v2)

cd apps/ai-engine-v2 && source venv/bin/activate

# Code quality
black . && isort .        # Format code
flake8 . --max-line-length=120  # Lint check
mypy .                    # Type checking

# Testing
pytest                    # Run test suite
pytest --cov              # Run with coverage

Environment Variables

This section provides a complete reference of all environment variables used across the platform.

Critical Variables (Required)

These variables are required for the application to function:

Variable	Used In	Description
NEXT_PUBLIC_SUPABASE_URL	Web, Database	Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Web, Database	Supabase anonymous key
SUPABASE_SERVICE_ROLE_KEY	Web, API, AI Engine	Supabase admin key
SUPABASE_URL	AI Engine v2	Supabase URL (server-side)
SECRET_KEY	AI Engine v2	App secret (min 32 chars in prod)
ENCRYPTION_MASTER_KEY	Database, API, AI Engine v2	Credential encryption

Web App (apps/web/.env.local)

# Supabase (Required)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Stripe Payments (Required for billing)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRO_PRICE_ID=price_...              # Optional: Pro plan price
STRIPE_ENTERPRISE_PRICE_ID=price_...       # Optional: Enterprise plan price

# AI Engine Connection
AI_ENGINE_URL=http://localhost:8001        # Default: http://localhost:8000
AI_ENGINE_V2_URL=http://localhost:8001     # Preferred over AI_ENGINE_URL
AI_ENGINE_API_KEY=your-api-key             # Default: dev-api-key

# Security & Encryption (Required)
ENCRYPTION_MASTER_KEY=your-32-byte-key     # Required for credential encryption

# Google OAuth (Required for Google integrations)
GOOGLE_OAUTH_CLIENT_ID=your-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
# Fallback names also supported:
# GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET

# Application URLs
NEXT_PUBLIC_BASE_URL=http://localhost:3000
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Admin Access
# Admin role is managed via the `profiles.role` column in the database.
# Set a user's role to 'admin': UPDATE profiles SET role = 'admin' WHERE id = '<user-id>';

# AI Features (Optional)
OPENAI_API_KEY=sk-...                      # For embeddings

# Internal API (Optional)
INTERNAL_API_KEY=your-32-char-min-key      # Service-to-service auth

AI Engine v2 (apps/ai-engine-v2/.env)

# Application
APP_ENV=development                         # development|staging|production|test
LOG_LEVEL=info                             # debug|info|warning|error|critical
API_HOST=0.0.0.0
API_PORT=8001
DEBUG=false

# Database (Required)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_PUBLIC_URL=                       # Defaults to SUPABASE_URL
DATABASE_URL=                              # Optional: Direct PostgreSQL URL

# Redis & Celery
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=                            # Optional
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/1
CELERY_WORKER_CONCURRENCY=2
CELERY_TASK_TIME_LIMIT=3600                # 1 hour
CELERY_TASK_SOFT_TIME_LIMIT=3000           # 50 minutes

# LLM API Keys (At least one required)
OPENROUTER_API_KEY=your-openrouter-key     # Recommended
OPENAI_API_KEY=sk-...                      # Alternative
ANTHROPIC_API_KEY=sk-ant-...               # Alternative

# LLM Configuration
DEFAULT_LLM_PROVIDER=openrouter            # openrouter|openai|anthropic
DEFAULT_LLM_MODEL=openai/gpt-4
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=4096
LLM_REQUEST_TIMEOUT=120

# Security (Required)
SECRET_KEY=your-32-char-minimum-secret-key
ENCRYPTION_MASTER_KEY=your-32-byte-key
CORS_ORIGINS=http://localhost:3000         # Comma-separated
INTERNAL_API_KEY=                          # Optional: Internal auth

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_MINUTE=60
RATE_LIMIT_REQUESTS_PER_HOUR=1000
RATE_LIMIT_CONCURRENT_EXECUTIONS=5

# LangGraph
LANGGRAPH_RECURSION_LIMIT=100
LANGGRAPH_CHECKPOINT_ENABLED=true
LANGGRAPH_TIMEOUT=300

# Execution Settings
EXECUTION_TIMEOUT=600
EXECUTION_MAX_RETRIES=3
EXECUTION_RETRY_DELAY=5

# Storage
STORAGE_BUCKET_NAME=automations
STORAGE_MAX_FILE_SIZE_MB=50

# Internal Communication
TRPC_BASE_URL=http://localhost:3000/api/trpc

# Google Services (Optional)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# Monitoring (Optional but recommended in production)
SENTRY_DSN=https://...@sentry.io/...

# Flower Dashboard
FLOWER_ADDRESS=0.0.0.0
FLOWER_PORT=5555
FLOWER_BASIC_AUTH=                         # user:password format

AI Engine Legacy (apps/ai-engine/.env)

# Application
APP_ENV=development
LOG_LEVEL=info
API_HOST=0.0.0.0
API_PORT=8000
DEBUG_MODE=false

# Database (Required)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
DATABASE_URL=                              # Optional: Direct PostgreSQL

# Redis
REDIS_URL=redis://localhost:6379

# LLM Keys (At least one required)
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=your-openrouter-key
CREWAI_API_KEY=                            # Optional

# Security
SECRET_KEY=your-secret-key
ENCRYPTION_MASTER_KEY=your-master-key

# Google OAuth
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# Internal API
AI_ENGINE_API_KEY=your-api-key
AI_ENGINE_INTERNAL_SECRET=your-internal-secret
TORUS_API_BASE_URL=http://localhost:3000

Packages (packages/*/.env)

The packages inherit environment variables from the app that imports them. Key variables:

# packages/database
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
ENCRYPTION_MASTER_KEY=...
GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...

# packages/api
STRIPE_SECRET_KEY=...
AI_ENGINE_V2_URL=...
AI_ENGINE_API_KEY=...
INTERNAL_API_KEY=...

Security Notes

1. Encryption keys must be 32 bytes when decoded (base64 or hex)
2. SECRET_KEY must be at least 32 characters in production
3. INTERNAL_API_KEY uses constant-time comparison for security
4. In production, localhost URLs are rejected
5. DEBUG must be false in production
6. SENTRY_DSN is highly recommended for production error tracking

Development Workflow

Adding a tRPC Endpoint

1. Create or modify router in packages/api/src/routers/
2. Export from packages/api/src/server.ts if new
3. Add types to packages/api/src/types/
4. Use in frontend with api.routerName.procedure.useQuery()

Adding a New Automation (AI Engine v2)

1. Create workflow in apps/ai-engine-v2/automations/
2. Inherit from BaseAutomation class
3. Register in apps/ai-engine-v2/orchestration/registry.py
4. Add automation entry to Supabase automations table

Database Changes

1. Create migration in supabase/migrations/
2. Lint: cd supabase && supabase db lint
3. Test locally: supabase db reset
4. Push to remote: pnpm db:push
5. Regenerate types: pnpm db:generate-types

SDK Publishing

The torivers-sdk Python package is published to PyPI using automated GitHub Actions workflows.

Versioning

Version bumps are managed with bump-my-version, which updates both torivers-sdk/pyproject.toml and torivers-sdk/src/torivers_sdk/__init__.py in a single commit and creates a sdk-v* tag.

cd torivers-sdk && source .venv/bin/activate

# Preview what will change
bump-my-version bump patch --dry-run --verbose

# Examples
bump-my-version bump --new-version 0.2.0b8  # Example beta cycle
bump-my-version bump pre_n                   # Next beta (0.2.0b8 → 0.2.0b9)
bump-my-version bump pre_l                   # Beta → RC (0.2.0b8 → 0.2.0rc1)
bump-my-version bump pre_l                   # RC → Stable (0.2.0rc1 → 0.2.0)
bump-my-version bump patch                   # Patch release (0.2.0 → 0.2.1)
bump-my-version bump minor                   # Minor release (0.2.0 → 0.3.0)

Publishing

After bumping, push the commit and tag to trigger the publish workflow:

git push && git push --tags

• Stable releases (e.g. sdk-v0.2.0) are published to PyPI via the pypi GitHub environment
• Pre-releases (e.g. sdk-v0.2.0b8, sdk-v0.2.0rc1) are published via the pypi-prerelease environment

Publishing uses OIDC Trusted Publishing (no API tokens needed). Pre-releases are ignored by default pip install — users must opt in with pip install --pre torivers-sdk.

Documentation

Document	Description
CLAUDE.md	AI development guidelines
ARCHITECTURE.md	System architecture deep dive
DATABASE_SCHEMA.md	Complete database design
MONOREPO_STRUCTURE.md	Monorepo organization
TECH_STACK_GUIDE.md	Technology decisions
LOCAL_DEVELOPMENT.md	Setup guide
PROJECT_REQUIREMENTS.md	Feature specifications

App-Specific Documentation

• apps/web/README.md - Frontend application
• apps/ai-engine-v2/README.md - AI orchestration engine
• apps/ai-engine/README.md - Legacy CrewAI service

Deployment

Production Stack

Component	Recommended Platform
Frontend	Vercel
AI Engine	AWS ECS / GCP Cloud Run
Database	Supabase Cloud
Redis	Upstash / AWS ElastiCache
Monitoring	Grafana Cloud

Deploy Frontend to Vercel

1. Connect GitHub repository to Vercel
2. Configure environment variables in Vercel dashboard
3. Set root directory to apps/web
4. Build command: cd ../.. && pnpm build --filter=web

Deploy AI Engine

# Build production image
cd apps/ai-engine-v2
docker build -t torivers-ai-engine:latest .

# Push to registry and deploy
docker push your-registry/torivers-ai-engine:latest

Contributing

1. Create a feature branch from main
2. Make changes following the codebase patterns
3. Run linting and type checks: pnpm lint && pnpm type-check
4. Use conventional commit messages (max 10-15 words)
5. Submit a pull request

Commit Format

feat(scope): add user wallet balance display
fix(api): resolve credential decryption error
chore(deps): update Next.js to 15.4.5

License

This project is proprietary software. See LICENSE file for details.

---

Version: 0.0.1 Last Updated: December 2025 Status: Active Development