Cloudflare Deployment Architecture

Overview

The Refresh App Web is deployed entirely on Cloudflare's global edge network using Cloudflare Workers and Pages. This provides low-latency access worldwide, automatic scaling, and high availability without managing servers.

Deployment Platform

Cloudflare Workers

What are Cloudflare Workers?

• Serverless JavaScript/TypeScript runtime

• V8 isolates (not containers)

• Deploy to 300+ data centers globally

• Sub-millisecond cold starts

• Automatic geographic routing

SvelteKit Integration:

• Adapter: @sveltejs/adapter-cloudflare

• SSR at the edge

• API routes as Worker endpoints

• Static assets bundled with Worker

Wrangler

Wrangler is Cloudflare's CLI tool for Workers:

• Build and bundle application

• Deploy to Cloudflare

• Manage environment variables

• Stream logs in real-time

• Manage custom domains

Deployment Environments

Environment Overview

Environment	Purpose	Trigger	URL	AWS Account
PR Sandbox	Feature testing	PR creation	[pr-number].dev.app.refresh.tech	469718319213
Development	Integration testing	Merge to main	dev.app.refresh.tech	469718319213
Staging	Pre-production validation	Dev deployment success	staging.app.refresh.tech	328237344502
Production	Live application	Staging deployment success	app.refresh.tech	231307122957

wrangler.toml Configuration

Defines Worker settings, environments, R2 bindings. See Reference: Configuration.

Build Process

Build Steps

1. Install Dependencies

   pnpm install

2. SvelteKit Build

   pnpm build

   This creates:

   • .svelte-kit/cloudflare/_worker.js - Main Worker script

   • .svelte-kit/cloudflare/ - Static assets and prerendered pages

3. Wrangler Deploy

   wrangler deploy --env <environment>

Build Outputs

.svelte-kit/cloudflare/
├── _worker.js           # Main Worker script (SSR + routing)
├── _app/
│   ├── immutable/       # Hashed static assets (long cache)
│   ├── version.json     # Build version
│   └── env.js           # Public env variables
└── [static files]       # Static assets from /static

Deployment Pipeline

CI/CD Workflow

┌──────────────────────────────────────────────────────────────┐
│                    GitHub Actions Workflow                   │
└──────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────┐
│  Step 1: Fetch Environment Variables from AWS SSM            │
│  • Configure AWS credentials (OIDC)                          │
│  • Run fetch-ssm-params.sh script                            │
│  • Create .dev.vars file                                     │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│  Step 2: Run Database Migrations                             │
│  • Fetch database config from SSM                            │
│  • Migrate read replicas first (all regions)                 │
│  • Migrate write region last                                 │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│  Step 3: Deploy to Cloudflare                                │
│  • Run: wrangler deploy --env <environment>                  │
│  • Upload Worker code                                        │
│  • Deploy to global edge network                             │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│  Step 4: Attach Custom Domain                                │
│  • Call Cloudflare API to attach custom domain               │
│  • Link Worker to domain                                     │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│  Step 5: Upload Secrets                                      │
│  • Run bulk-upload-secrets.sh script                         │
│  • Upload all secrets from .dev.vars to Cloudflare           │
└──────────────────────────────────────────────────────────────┘

Deployment Trigger Flow

PR Created
    │
    ▼
PR Sandbox Deploy (Automatic)
    │
PR Merged to main
    │
    ▼
Development Deploy (Automatic)
    │
    ├─ Success ──▶ Staging Deploy (Automatic)
    │                  │
    │                  ├─ Success ──▶ Production Deploy (Automatic)
    │                  │
    │                  └─ Failure ──▶ Stop (Alert team)
    │
    └─ Failure ──▶ Stop (Alert team)

Custom Domains

Domain Configuration

Cloudflare DNS:

• All domains managed in Cloudflare DNS

• CNAME or ALIAS records point to Workers

• Automatic SSL/TLS certificate provisioning

• HTTP → HTTPS redirect enforced

Custom Domain Attachment: Each deployment attaches a custom domain via Cloudflare API:

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/domains" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "hostname": "app.refresh.tech",
    "service": "app-web-production",
    "zone_id": "$ZONE_ID"
  }'

DNS Records

Domain	Type	Target	Environment
app.refresh.tech	CNAME	app-web-production.workers.dev	Production
staging.app.refresh.tech	CNAME	app-web-staging.workers.dev	Staging
dev.app.refresh.tech	CNAME	app-web-development.workers.dev	Development

Environment Variables & Secrets

Secret Management Strategy

AWS Systems Manager (SSM) Parameter Store:

• All secrets stored in AWS SSM

• Separate AWS account per environment

• Fetched during CI/CD deployment

• Never committed to git

Cloudflare Secrets:

• Uploaded to Cloudflare Workers after deployment

• Encrypted at rest

• Accessible via env in Workers

• Updated via bulk upload script

Environment Variable Flow

AWS SSM Parameter Store
    │
    │ fetch-ssm-params.sh
    ▼
.dev.vars file (local, gitignored)
    │
    │ bulk-upload-secrets.sh
    ▼
Cloudflare Workers Secrets
    │
    │ Runtime access
    ▼
Application Code (process.env or platform.env)

Variable Categories

1. Public Variables (PUBLIC_*):

• Exposed to client-side code

• Not sensitive

• Stored in PUBLIC_JWK_JSON, PUBLIC_POSTHOG_API_KEY, etc.

2. Private Variables:

• Server-side only

• Database credentials, API keys, OAuth secrets

• Never sent to client

3. Database Configuration:

• Stored as JSON in database_config SSM parameter

• Contains connection strings for all regions

• Parsed and used for migrations and runtime

Smart Placement

Placement Strategy

Cloudflare's "smart" placement mode:

• Analyzes request patterns

• Routes requests to optimal data center

• Balances between user location and data location

• Minimizes latency

Configuration:

[placement]
mode = "smart"

Data Locality

User Request Flow:

1. Request hits nearest Cloudflare edge

2. Worker executes at edge

3. Database query routed to nearest read replica

4. Response served from edge

Performance Characteristics

Cold Start Performance

• V8 Isolates: Sub-millisecond cold starts

• Warm Workers: < 1ms response time

• Global Distribution: 300+ locations

Resource Limits

Limit	Value
CPU Time	50ms (can be extended)
Memory	128 MB
Request Size	100 MB
Response Size	100 MB
Subrequests	50

Caching Strategy

Static Assets:

• Long cache headers for hashed assets (_app/immutable/)

• Edge caching via Cloudflare CDN

• Browser caching for repeat visits

Dynamic Content:

• No default caching (SSR on each request)

• Cache headers configurable per route

• Session-based content not cached

Monitoring & Observability

Cloudflare Analytics

Metrics Available:

• Request count

• Error rate (4xx, 5xx)

• Response time (p50, p95, p99)

• Bandwidth usage

• Geographic distribution

Dashboard: Access via Cloudflare Dashboard → Workers & Pages → [Worker Name] → Analytics

Real-Time Logs

Wrangler Tail:

wrangler tail --env production

Streams real-time logs from production Workers, including:

• Console logs

• Exceptions

• Request/response data

Error Tracking

PostHog Integration:

• Automatic exception capture

• User session recording

• Custom event tracking

Rollback Strategy

1. Wrangler: Deploy previous commit

2. Dashboard: Use Cloudflare deployment history

3. Git revert: Revert commit and push (triggers auto-deploy)

Test rollback in dev/staging first. See Operations: Deployment Guide.

Disaster Recovery

High Availability

Cloudflare Workers:

• 100% uptime SLA

• Automatic failover across data centers

• No single point of failure

Database:

• Multi-region read replicas

• Automatic failover in Neon

• Point-in-time recovery (Neon feature)

Backup Strategy

Code:

• All code in git (GitHub)

• Tagged releases for production deployments

Database:

• Neon automatic backups

• Point-in-time recovery (30 days)

Secrets:

• AWS SSM with versioning

• Cloudflare secrets backup in SSM

Local Development

Use pnpm wrangler:dev for local Workers runtime with hot reload and R2 simulation. See Developer: Local Development.

Cost Optimization

Cloudflare Workers Pricing

Free Tier:

• 100,000 requests/day

• First 10ms CPU time per request free

Paid Plan (Bundled):

• $5/month

• 10 million requests included

• $0.50 per additional million requests

Cost Monitoring

• Cloudflare Dashboard shows request volume

• Alert on unusual spikes

• Optimize cold starts and CPU usage

Related Documentation

• System Overview - Overall architecture

• Deployment Guide - Operational procedures

• Environment Management - Secret management

• DNS & Custom Domains - DNS configuration

---

Last updated: October 2025