Environments

Model: Branch-as-Environment

Convertella uses Cloudflare Pages branch previews as the staging mechanism. Every Git branch automatically gets a unique preview URL — there is no separate staging server or test environment to maintain.

Layer	URL	Database	Who
Local dev	`http://localhost:4321`	Testing Neon DB (`.env`)	Developer
Feature branch	`convertella-admin-<branch>.pages.dev`	Testing Neon DB (shared)	Developer + reviewer
Default branch	`convertella-admin-<slug>.pages.dev`	Testing Neon DB (shared)	Continuous deployment
Production	`admin.convertella.app`	Production Neon DB	End users

Why this works

Cloudflare Pages automatically deploys every push to every branch as a preview deployment:

feature/add-csv-export → https://convertella-admin-add-csv-export.pages.dev
fix/login-otp-timing  → https://convertella-admin-fix-login-otp-timing.pages.dev
spike/cf-runtime      → https://convertella-admin-spike-cf-runtime.pages.dev

Preview deployments inherit the project’s environment variables (DATABASE_URL, CLOUDFLARE_API_TOKEN, etc.) so they are fully functional — they connect to the same testing database, send real OTP emails, and talk to Cloudflare APIs.

Database Strategy

Database	Used by	Purpose
Testing Neon DB	Local dev + all branch previews + default branch	Feature development, testing, staging verification
Production Neon DB	Production Pages deployment	Live tenant data

No third DB is needed because:

Branch previews already isolate code changes from production

Schema migrations run against the testing DB first and are verified in preview deployments

Cloudflare Pages automatically resets preview deployments on each push (no state to clean up)

Branch Lifecycle

Developer push → Pages builds → Preview URL ready (2-3 min)
     ↓
Test in preview → Fix → Push again → Updated preview
     ↓
Merge to default branch → Production build + deploy
     ↓
Delete feature branch → Preview URL deactivated automatically

Key Rules

Any branch can be previewed — no special naming convention required
All previews share the testing database — be mindful of test data collisions
Production deploys only from the default branch (spike/cf-runtime / main)
Database migrations run manually against testing first; production migrations run only when deploying production
Destructive migrations (DROP, ALTER COLUMN) should avoid impacting other branch previews — prefer additive changes
Preview URLs are public — anyone with the URL can access them (use Cloudflare Access for sensitive admin previews if needed)

Production Deployment

Production has its own Pages project with:

A separate Neon database (production branch)
Separate R2 buckets
Separate Cloudflare API tokens (scoped to production resources)
Cloudflare for SaaS custom hostnames for buyer portals

The wrangler.toml [env.production] section configures the production project name and routes.

Comparison: This vs. Three-Environment Model

Concern	Traditional dev/staging/prod	Branch-as-Environment (this project)
Isolation	Separate DBs per stage	Shared testing DB, separate prod DB
Cost	~$50-100/mo extra	$0 extra (branch previews included in Pages plan)
Setup complexity	High (3x infra, 3x env vars, 3x pipelines)	Low (one config, branches handle the rest)
Schema migration safety	Test migrations on staging first	Test migrations locally + in branch preview
Data privacy	Staging can have anonymized prod clone	Shared testing DB — careful with real data
Team collaboration	Dedicated staging URL for QA	Each branch gets its own URL