2. System Architecture

Vespertene Shop follows a decoupled headless commerce architecture. The Next.js storefront communicates with the Medusa backend via REST API. All file storage is handled by Cloudflare R2. Payments are processed by Stripe, with webhooks firing back to the Medusa backend to trigger order fulfilment and download link generation.

2.1 Services & Responsibilities

Service	Role	URL
Vercel (Next.js)	Storefront — SSR, caching, auth guards	shop.vespertene.com
Fly.io (Medusa v2)	Backend API, business logic, webhooks	api.shop.vespertene.com
Supabase (PostgreSQL)	Primary database, connection pooling via PgBouncer	Internal only
Cloudflare R2	ZIP file storage, presigned URL delivery	CDN-backed
Stripe	Payment processing, refunds, webhook events	External
Resend	Transactional emails — orders, invites, resets	External
Cloudflare DNS	DNS routing, DDoS protection, Bot Fight Mode	DNS layer
Sentry	Frontend + backend error tracking	External
Better Uptime	Uptime monitoring and alerts	External

2.2 Request Flow

Customer DNS request → Cloudflare → Vercel (storefront) or Fly.io (API)
Storefront fetches product/order data from Medusa API with JWT auth
Stripe Elements communicates directly with Stripe — card data never touches your server
Stripe webhook fires to Medusa backend on payment success
Medusa generates download links and triggers Resend confirmation email
Download request → Medusa validates token → R2 presigned URL (15 min expiry)
Browser redirects to R2 presigned URL → ZIP served directly from Cloudflare CDN

2.3 Architecture Diagram

Customer Browser
      │
      ▼
Cloudflare DNS/CDN ──────────────────────────────┐
      │                                           │
      ▼                                           ▼
Vercel (Next.js) ──── API calls ────► Fly.io (Medusa v2)
      │                                     │    │    │
      │ Stripe.js                           │    │    │
      ▼                                     ▼    ▼    ▼
   Stripe ◄──── Webhook ────────── Supabase  R2  Resend

⚠️

Stripe card data never passes through your server. Stripe Elements handles it directly — you only receive a payment intent confirmation.

2.4 Environments

Environment	Backend	Frontend	Database	Purpose
Development	localhost:9000	localhost:3000	Local PostgreSQL	Local development
Staging	Fly.io (staging app)	Vercel Preview	Supabase dev schema	Pre-production testing
Production	Fly.io (prod app)	Vercel Production	Supabase prod schema	Live users

1. Project Overview 3. Database Schema