┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Browser       │────▶│   Next.js 16    │────▶│   Supabase      │
│   (Client)      │     │   App Router    │     │   PostgreSQL    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                      │                        │
         │ presigned            │ rawPrompt +            │ RPC calls
         │ URLs                 │ image-to-image         │ (create_job,
         ▼                      ▼                        │  add_credits)
┌─────────────────┐     ┌─────────────────┐             │
│  Cloudflare R2  │     │   Google        │             │
│  (Images)       │     │   Gemini        │             │
└─────────────────┘     └─────────────────┘             │
                                                         │
                    ┌────────────────────────────────────┘
                    ▼
            ┌─────────────────┐
            │  prompt-bench   │
            │  CLI Testing    │
            └─────────────────┘

// Browser client - RLS enforced, uses cookies
import { createClient } from '@/lib/supabase/client'

// Server client - SSR, RLS enforced, uses headers
import { createClient } from '@/lib/supabase/server'

// Admin client - BYPASSES RLS, for system operations
import { getAdminClient } from '@/lib/supabase/admin'

1. User clicks "Generate" in UI
   └─▶ src/app/generate/page.tsx (form submission)

2. Form submits to API
   └─▶ POST /api/generate (src/app/api/generate/route.ts)

3. API validates & creates job
   └─▶ createJob() RPC call (src/lib/db/jobs.ts)
   └─▶ consume_credits RPC (checks balance, deducts)

4. API calls Gemini
   └─▶ geminiProvider.rawPrompt() (src/lib/ai/providers/gemini.ts)
   └─▶ Google Gemini API

5. Image generated
   └─▶ Base64 response from Gemini

6. Store image in R2
   └─▶ uploadToR2() (src/lib/r2/index.ts)
   └─▶ Cloudflare R2 bucket

7. Save record to database
   └─▶ saveGeneratedImage() (src/lib/db/generated-images.ts)

8. Update job status
   └─▶ updateJobStatus() (src/lib/db/jobs.ts)

9. Return response
   └─▶ { imageUrl, creditsRemaining, jobId }

1. User selects file
   └─▶ src/components/forms/* (file input)

2. Request presigned URL
   └─▶ POST /api/upload (src/app/api/upload/route.ts)
   └─▶ getPresignedUrl() (src/lib/r2/index.ts)

3. Browser uploads directly to R2
   └─▶ PUT request to presigned URL
   └─▶ Cloudflare R2 (NOT through server)

4. Confirm upload
   └─▶ createUpload() (src/lib/db/uploads.ts)
   └─▶ Save upload record in Supabase

1. User clicks "Buy Credits"
   └─▶ src/app/pricing/page.tsx

2. Create Stripe checkout session
   └─▶ POST /api/stripe/checkout (src/app/api/stripe/checkout/route.ts)
   └─▶ stripe.checkout.sessions.create()

3. User completes payment on Stripe
   └─▶ Redirects to Stripe hosted checkout

4. Stripe sends webhook
   └─▶ POST /api/webhooks/stripe (src/app/api/webhooks/stripe/route.ts)
   └─▶ Verify signature, handle event

5. Add credits to user account
   └─▶ add_credits RPC (src/lib/db/credits.ts)
   └─▶ Updates users.credits, creates credit_transaction record

6. Redirect to success page
   └─▶ src/app/success/page.tsx

1. User creates batch
   └─▶ src/app/batch/new/page.tsx (batch form)

2. Submit batch
   └─▶ POST /api/batch (src/app/api/batch/route.ts)
   └─▶ createBatch() (src/lib/db/batch.ts)

3. Create jobs for each item
   └─▶ Loop: createJob() RPC for each batch item

4. Process jobs
   └─▶ Background processing (same as generation flow)

5. View batch status
   └─▶ src/app/batch/[batchId]/page.tsx
   └─▶ GET /api/batch/[id] (src/app/api/batch/[id]/route.ts)
   └─▶ getBatchJobs() (src/lib/db/batch.ts)

prompt-bench/
├── cli.ts                    # Entry point
├── core/                     # Core types, errors, compiler
│   ├── types.ts              # Template, Test, Evaluation types
│   ├── errors.ts             # Result<T> type
│   ├── compiler.ts           # Template variable compilation
│   ├── evaluator.ts          # AI-powered evaluation
│   └── statistics.ts         # Score analysis
├── commands/                 # CLI commands
│   ├── run.ts                # Generate images
│   ├── evaluate.ts           # Score images
│   ├── compare.ts            # A/B testing
│   ├── report.ts             # HTML reports
│   ├── test.ts               # Full pipeline
│   ├── sync.ts               # Sync templates to DB
│   └── improve.ts            # AI-powered iteration
├── templates/                # Template definitions
│   ├── registry.ts           # Template registry
│   └── *.ts                  # Template files
└── db/                       # Database helpers
    └── client.ts             # Supabase admin client

# Generation-related code
grep -rl "generation\|generate" --include="*.ts" src/app src/lib

# Credit system
grep -rl "credit\|balance" --include="*.ts" src/lib/db src/app/api

# R2 storage
grep -rl "r2\|presigned\|upload" --include="*.ts" src/lib src/app/api

# Gemini AI
grep -rl "gemini\|rawPrompt" --include="*.ts" src/lib/ai

# Stripe payments
grep -rl "stripe\|checkout\|webhook" --include="*.ts" src/lib/stripe src/app/api

# Find all API routes
find src/app/api -name "route.ts"

# Find all page components
find src/app -name "page.tsx"

# Find all Server Actions
grep -rn "use server" --include="*.ts" src/

# Find all Client Components
grep -rn "use client" --include="*.tsx" src/

# Find all database queries
ls src/lib/db/*.ts

# Find all Supabase RPC calls
grep -rn "\.rpc(" --include="*.ts" src/

# Find where specific error is thrown
grep -rn "CreditError\|InsufficientCredits" --include="*.ts" src/

# Find error handling patterns
grep -rn "try.*catch\|\.catch(" --include="*.ts" src/

# Find where jobs fail
grep -rn "status.*failed\|error" --include="*.ts" src/lib/db/jobs.ts

# Find R2 upload errors
grep -rn "UploadError\|presigned.*error" --include="*.ts" src/lib/r2

# Development
bun dev                    # Start dev server
bun build                  # Production build
bun test                   # Run tests

# prompt-bench
bun bench test --template <slug> --batch <file>    # Full pipeline
bun bench evaluate --label <batch-label>           # Score images
bun bench compare --baseline <l1> --candidate <l2> # A/B testing
bun bench open-last-report                         # Open report

# Supabase
npx supabase db push       # Push schema changes
npx supabase gen types ts  # Generate TypeScript types