Skip to content

CLOUDFLARE_IDEAL_SETUP.md

Latest commit

 

History

History
489 lines (382 loc) · 11 KB

CLOUDFLARE_IDEAL_SETUP.md

File metadata and controls

489 lines (382 loc) · 11 KB

Ideal Cloudflare Workers Setup for Binary Math System

Executive Summary

Your project is production-ready for Cloudflare Workers. Here's the ideal architecture:

GitHub (private repo)
    ↓ (push to main)
GitHub Actions (CI/CD)
    ├─→ Test API & Web
    ├─→ Build API
    └─→ Deploy to Cloudflare Workers (automatic)
         ↓
    Cloudflare Workers (binary-math-api)
         ├─→ KV Storage (sessions, cache)
         ├─→ Turso Database (persistent data)
         └─→ Custom Domain: api.binarymath.dev

    Cloudflare Pages (binary-math-web)
         └─→ Custom Domain: binary-math.dev (or subdomain)

What Gets Pushed to Cloudflare Workers

1. API Worker (binary-math-api)

The compiled TypeScript Worker that runs at the edge:

binary-math-api/
├── src/
│   ├── index.ts           ← Entry point (Hono app)
│   ├── routes/
│   │   ├── auth.ts        (registration, login, session)
│   │   ├── problems.ts    (problem retrieval, generation)
│   │   ├── sessions.ts    (learning session CRUD)
│   │   └── validation.ts  (answer validation, XP calc)
│   ├── db/
│   │   ├── index.ts       (Turso connection)
│   │   └── schema.ts      (table definitions)
│   └── lib/
│       ├── ai-service.ts  (OpenRouter integration)
│       ├── auth.ts        (JWT, hashing)
│       └── validators.ts  (input validation)
│
├── wrangler.toml          ← Worker configuration
├── wrangler.jsonc         ← Alternative config
└── drizzle/
    └── migrations/        ← Database schema

What actually deploys:

  • Compiled JavaScript bundle
  • Wrangler configuration
  • Environment variables (via GitHub Secrets)
  • Database connection strings (from secrets)

2. Web App (binary-math-web)

The frontend deployed to Cloudflare Pages:

binary-math-web/
├── src/
│   ├── components/        ← React components
│   ├── routes/            ← Page routing
│   ├── lib/
│   │   └── api-client.ts  (calls to /api)
│   └── styles/
├── dist/                  ← Built output
└── vite.config.ts

What deploys:

  • Static HTML, CSS, JS
  • Built React app
  • API client configured to call /api

Ideal Deployment Strategy

Phase 1: Initial Setup ✅ (You are here)

Status: Complete

  • Private GitHub repository
  • GitHub Actions CI/CD pipeline
  • Cloudflare credentials ready
  • Database (Turso) configured
  • API fully built and tested
  • Web frontend built and tested

Phase 2: Deploy to Cloudflare (Next)

What to do:

  1. Add GitHub Secrets (5 minutes)

    CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
TURSO_URL
TURSO_AUTH_TOKEN
OPENROUTER_API_KEY (optional)

  2. Trigger first deployment

    git push origin main

    → GitHub Actions runs automatically → Tests pass → Deploys to Cloudflare Workers → Deploys web to Cloudflare Pages

  3. Verify deployment

    • API: https://api.binarymath.dev/health
    • Web: https://binary-math.pages.dev

Phase 3: Custom Domain Setup (Optional)

  • Point binary-math.dev to Cloudflare Pages
  • Point api.binarymath.dev to Cloudflare Workers
  • Enable SSL/TLS (automatic)

What Each Component Does

Cloudflare Workers (API)

Location: api.binarymath.dev

Runs at the edge globally:

  • 200+ data centers
  • < 10ms latency anywhere
  • Handles all API requests
  • Connects to Turso database
  • Manages user sessions
  • Calculates XP and gamification
  • Rate limiting (via KV)

18 Endpoints:

POST   /api/auth/register
POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/me

GET    /api/problems
GET    /api/problems?type=binary-conversion&difficulty=beginner
GET    /api/problems/:id
POST   /api/problems (admin)

POST   /api/sessions
GET    /api/sessions/:id
PUT    /api/sessions/:id
DELETE /api/sessions/:id
POST   /api/sessions/:id/pause
POST   /api/sessions/:id/resume
GET    /api/sessions/user/:userId
GET    /api/sessions/analytics

POST   /api/validate
GET    /api/validate/stats
GET    /api/validate/history

Cloudflare Pages (Web)

Location: binary-math.pages.dev (or custom domain)

Serves the React frontend:

  • Automatically redeployed on git push
  • Global CDN distribution
  • Instant HTTPS
  • Zero configuration

Key Features:

  • Login/signup page
  • Lesson selector (Binary Basics, Logic Gates, Truth Tables)
  • Practice mode with adaptive difficulty
  • Progress dashboard
  • Profile and statistics
  • Mobile responsive

Turso Database

Persistent data layer (not at edge, but globally distributed):

  • 9 tables with full schema
  • 1600 pre-seeded problems
  • User accounts and sessions
  • Progress tracking
  • Achievements and gamification
  • Automatic backups

Connection: From Workers via LibSQL client

KV Storage

Fast, edge-local caching:

  • Session tokens (< 1ms access)
  • User preferences
  • Leaderboards (cache)
  • Rate limiting counters
  • Admin flags

Optimal Architecture for Your Use Case

1. For Student Learning

Student opens browser
    ↓
Cloudflare Pages serves web app
    ↓
Student logs in
    ↓
Workers validates credentials + creates session
    ↓
Session token stored in KV (instant access)
    ↓
Student gets problems from Database
    ↓
Student solves problem
    ↓
Answer validated, XP calculated, streak updated
    ↓
Result saved to Database
    ↓
Profile updates instantly

Performance: All requests < 100ms globally

2. For Instructors/Analytics

Instructor dashboard calls:
/api/validate/stats
    ↓
Workers calculates from Database + KV cache
    ↓
Returns student performance, streaks, achievements
    ↓
Updates in real-time as students solve problems

3. For Scaling

10 students → 10 requests/sec
100 students → 100 requests/sec
1000 students → Still fast (Workers scales automatically)

Database: Turso handles 100k+ queries/sec
KV: Handles 1M+ reads/sec (infinite scaling)
Pages: Serves static assets from 200+ edge locations

Step-by-Step Deployment Checklist

Pre-Deployment (You're doing this now)

  • Private GitHub repo created
  • CI/CD pipeline configured
  • API tests passing (21/21)
  • Web build successful
  • Database schema ready
  • Credentials secured as GitHub Secrets

Deployment (Next 30 minutes)

  1. Set GitHub Secrets (5 min)

    # Settings → Secrets → Actions → Add these:
CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
TURSO_URL
TURSO_AUTH_TOKEN
OPENROUTER_API_KEY

  2. Trigger deployment (1 min)

    git push origin main
# or make any commit and push

  3. Monitor GitHub Actions (10 min)

    • Go to Actions tab
    • Watch test stage (should pass in ~2 min)
    • Watch deploy stage (should complete in ~5 min)
    • Check for any errors

  4. Verify deployments (5 min)

    # Test API
curl https://api.binarymath.dev/health
# Should return 200 OK

# Test Web
# Visit https://binary-math.pages.dev in browser
# Should see login page

  5. Test end-to-end (5 min)

    • Sign up for account
    • Start a lesson
    • Complete a problem
    • Check progress updates

Post-Deployment

  • API responding on custom domain
  • Web app loads in browser
  • Login/signup works
  • Can start lessons
  • Problems validate answers
  • XP/streaks calculate correctly

Configuration Details

wrangler.toml (What We Push)

name = "binary-math-api"
type = "service"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[env.production]
routes = [
  { pattern = "api.binarymath.dev", custom_domain = true }
]

[[kv_namespaces]]
binding = "KV"
id = "binary-kv"

# Environment variables injected via GitHub Actions
# See DEPLOYMENT_GUIDE.md

GitHub Actions (What Triggers Deployment)

# .github/workflows/deploy.yml

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    # Tests both API and Web

  deploy-api:
    needs: test
    if: github.ref == 'refs/heads/main'
    # Deploys to Cloudflare Workers

  deploy-web:
    needs: test
    if: github.ref == 'refs/heads/main'
    # Deploys to Cloudflare Pages

Environment Variables

In GitHub Secrets (encrypted, never shown):

CLOUDFLARE_API_TOKEN=<token>
CLOUDFLARE_ACCOUNT_ID=<id>
TURSO_URL=libsql://...
TURSO_AUTH_TOKEN=<token>
OPENROUTER_API_KEY=<key>

Injected into Workers via:

  • Environment sections in wrangler.toml
  • Cloudflare dashboard UI
  • Automated by GitHub Actions

Ideal Upgrades (Future)

Now (MVP - What we have)

  • ✅ Core API + Database
  • ✅ Web frontend
  • ✅ Authentication
  • ✅ Lessons + problems
  • ✅ Progress tracking
  • ✅ Gamification (XP, streaks, achievements)

Phase 2 (Enhancement)

  • Instructor dashboard
  • Class management
  • Real-time collaboration (multiple students on same problem)
  • Advanced analytics (heat maps, error patterns)
  • Mobile app (React Native)

Phase 3 (Scale)

  • Advanced caching strategies
  • Analytics warehouse (Neon + DuckDB)
  • Email notifications
  • Integration with LMS (Canvas, Blackboard)
  • Offline mode

Cost Estimate (Free Tier)

Component Tier Cost
Cloudflare Workers Free $0 (100k req/day)
Cloudflare Pages Free $0 (unlimited deploys)
KV Storage Free $0 (100k reads/day)
Turso Database Free $0 (~15GB)
GitHub Actions Free $0 (public, 2000 min/mo)
Domain (optional) Varies $10-15/yr
TOTAL $0-15/month

Scales to paid tier only when you exceed free limits (unlikely for educational use).

Support & Debugging

If deployment fails:

  1. Check GitHub Actions logs

  2. Common issues

    • Missing GitHub Secrets → Add them
    • Wrong credentials → Regenerate in Cloudflare
    • Node version mismatch → Use 20.x
    • Build errors → Run npm run build locally

  3. Test locally first

    cd binary-math-api
npm run build
npx wrangler deploy --dry-run

If Workers don't respond:

  1. Check Cloudflare dashboard
  2. Verify API token is valid
  3. Check function logs: wrangler tail
  4. Verify database connection: wrangler execute --name test

Summary

Your ideal setup is:

✅ Private GitHub → Safe code storage ✅ Automated CI/CD → Tests before deploy ✅ Cloudflare Workers → Global API at edge ✅ Cloudflare Pages → Static web hosting ✅ Turso Database → Persistent data ✅ GitHub Secrets → Secure credentials

To activate:

  1. Add 5 secrets to GitHub
  2. Push to main
  3. Done - automatic deployment

Result: Production-grade learning platform, globally distributed, instantly scalable, zero ops.

Next: Follow DEPLOYMENT_GUIDE.md to add secrets and trigger your first deployment.