Architecture Overview

CutX runs on Cloudflare’s edge platform as three independent services that communicate through queues, webhooks, and a shared PostgreSQL database.

System Diagram

┌─────────────────────────────────────────────────────┐
│                    Cloudflare Edge                    │
│                                                      │
│  ┌──────────────┐    ┌──────────┐    ┌───────────┐  │
│  │   Main App   │───→│  Queue   │───→│ Pipeline  │  │
│  │  (Astro SSR) │    │(cutx-jobs)│    │  Worker   │  │
│  │  Pages       │    └──────────┘    └─────┬─────┘  │
│  └──────┬───────┘                          │        │
│         │                            ┌─────▼─────┐  │
│         │                            │ Replicate  │  │
│         │                            │    API     │  │
│         │                            └─────┬─────┘  │
│         │                                  │        │
│         │         ┌───────────┐      ┌─────▼─────┐  │
│         │         │  Webhook  │◀─────│ Replicate  │  │
│         │         │  Worker   │      │ Callback   │  │
│         │         └─────┬─────┘      └───────────┘  │
│         │               │                           │
│  ┌──────▼───────────────▼──────┐    ┌───────────┐  │
│  │     PostgreSQL (Hyperdrive)  │    │  R2 Bucket │  │
│  │         cutx database        │    │ cutx-media │  │
│  └─────────────────────────────┘    └───────────┘  │
└─────────────────────────────────────────────────────┘

Services

Main App (Cloudflare Pages)

The primary application — an Astro SSR site deployed to Cloudflare Pages.

Responsibilities:

• User-facing UI (dashboard, studio, settings)
• REST API endpoints (/api/*)
• Authentication (magic link, GitHub OAuth, JWT)
• Credit management and Stripe billing
• Job creation and queue dispatch
• Whatnot seller tools (inventory, shows, payouts)

Bindings:

• HYPERDRIVE — PostgreSQL connection pool
• QUEUE — Cloudflare Queue producer (cutx-jobs)
• MEDIA — R2 bucket for generated assets
• AI — Workers AI for copy generation

Pipeline Worker (Cloudflare Worker)

A queue consumer that processes generation jobs.

Responsibilities:

• Dequeue jobs from cutx-jobs queue
• Route jobs to the correct handler by type
• Run synchronous jobs (copy, scrape) inline
• Submit async jobs to Replicate API
• Handle retries (up to 3 attempts per message)
• Refund credits on failure

Bindings:

• HYPERDRIVE — PostgreSQL connection pool
• MEDIA — R2 bucket for outputs
• AI — Workers AI for copy/scrape jobs

Queue config:

• Max batch size: 5
• Batch timeout: 30s
• Max retries: 3
• Dead letter queue: cutx-jobs-dlq

Webhook Worker (Cloudflare Worker)

Receives external callbacks from third-party services.

Responsibilities:

• Replicate prediction webhooks (async job completion)
• Stripe billing webhooks (payment events)
• Download generated media from Replicate to R2
• Transition jobs to completed/failed

Bindings:

• HYPERDRIVE — PostgreSQL connection pool
• MEDIA — R2 bucket for downloaded outputs

Data Flow: Generation Request

Here’s the complete flow for an async generation (e.g., static ad):

1. User POST /api/generate/static-ad
2. Main app validates input, checks credits
3. Deduct credits, create job (status: pending)
4. Send message to cutx-jobs queue (status: queued)
5. Pipeline worker dequeues message (status: processing)
6. Pipeline submits to Replicate API
7. Replicate processes the image (30s–5min)
8. Replicate sends webhook to webhook worker
9. Webhook worker downloads image to R2
10. Webhook worker marks job completed
11. User polls GET /api/jobs/<id> → sees completed + output URL

Shared Infrastructure

PostgreSQL (via Hyperdrive)

All three services connect to the same PostgreSQL database through Cloudflare Hyperdrive, which provides connection pooling and caching at the edge.

• Database: cutx on RackNerd VM
• Connection: SSL-encrypted via Hyperdrive
• Pooling: Automatic connection reuse across requests

R2 Object Storage

Generated media (images, videos, audio) is stored in the cutx-media R2 bucket. Assets are served via public R2 URLs or Cloudflare CDN.

Cloudflare Queue

The cutx-jobs queue decouples job creation from processing:

• Producer: Main app enqueues jobs
• Consumer: Pipeline worker processes jobs
• DLQ: cutx-jobs-dlq catches messages that fail after all retries