Leapify

The backend for DLSU CSO LEAP event websites. Leapify ships as:

| Mode | When to use | | :--- | :--- | | Standalone Worker | You want a zero-code deploy — just configure secrets and run wrangler deploy | | npm module | You have your own Worker / Next.js / SvelteKit app and want to mount Leapify inside it |

Both modes share exactly the same routes, auth, caching, and email logic.

Mode 1 — Standalone Worker

No code required. Clone, configure, deploy.

git clone https://github.com/access-dlsu/leapify
cd leapify
npm install
cp wrangler.toml.example wrangler.toml

Edit wrangler.toml with your D1 database ID and KV namespace ID, then set your secrets:

# CORS — comma-separated allowed origins
wrangler secret put ALLOWED_ORIGINS
# → "https://yoursite.com,https://www.yoursite.com"

# Firebase
wrangler secret put FIREBASE_PROJECT_ID
wrangler secret put FIREBASE_WEB_API_KEY

# Google Forms
wrangler secret put GFORMS_SERVICE_ACCOUNT_JSON
wrangler secret put GFORMS_WEBHOOK_SECRET

# Contentful
wrangler secret put CONTENTFUL_SPACE_ID
wrangler secret put CONTENTFUL_ACCESS_TOKEN
wrangler secret put CONTENTFUL_ENVIRONMENT

# Amazon SES (primary email)
wrangler secret put SES_REGION
wrangler secret put SES_ACCESS_KEY_ID
wrangler secret put SES_SECRET_ACCESS_KEY
wrangler secret put SES_FROM_ADDRESS

# Resend (optional email fallback — omit to disable)
wrangler secret put RESEND_API_KEY
wrangler secret put RESEND_FROM_ADDRESS

# Internal route security
wrangler secret put INTERNAL_API_SECRET

Build and deploy:

npm run build
wrangler deploy

Verify:

curl https://your-worker.your-subdomain.workers.dev/health
# → { "status": "ok", "providers": { "ses": true, "resend": false } }

wrangler.toml.example has full comments for every binding. See .dev.vars.example for local dev.

Mode 2 — npm module

Install into your own project and mount the handler:

npm install leapify

Server layer (Cloudflare Worker / Pages Function):

import { createLeapify } from 'leapify'

export default createLeapify({
  allowedOrigins: ['https://yourdomain.com'],
})

Browser / client components:

import { createLeapifyClient, getLeapifyToken } from 'leapify/client'
import { auth } from '@/lib/firebase'

const api = createLeapifyClient(
  process.env.NEXT_PUBLIC_API_URL!,
  () => getLeapifyToken(auth.currentUser),
)

const events = await api.getEvents()   // → LeapEvent[]
const config = await api.getConfig()   // → SiteConfig
const me     = await api.getMe()       // → UserProfile | null

Full setup and per-endpoint examples → Frontend Integration Guide

How It Works

Leapify exposes /api/ endpoints that your frontend consumes. The backend handles Firebase Auth, Cloudflare D1 (database), Contentful (CMS), and transactional email (Amazon SES primary / Resend fallback) — all credentials live in .env / wrangler.toml, never in browser code.

• /api/* — restricted to your site's origin (allowedOrigins CORS gate)
• /health — publicly accessible for uptime monitoring; reports which email providers are configured

Tech Stack

| Layer | Technology | Purpose | | :------------- | :---------------------- | :--------------------------------------------------------- | | Framework | Hono | Edge-optimized, <1ms cold start | | ORM | Drizzle + D1 | Type-safe SQL on Cloudflare's serverless SQLite | | Validation | Zod | Runtime schema validation | | Cache | Cloudflare KV + CDN | JWT caching, slot availability, edge response cache | | CMS | Contentful | Headless CMS for all event/FAQ/site content | | Email | Amazon SES + CF Queues | Async transactional email — SES primary, Resend fallback | | Auth | Firebase Auth | Google Sign-In, restricted to @dlsu.edu.ph | | Testing | Vitest + CF pool | Unit + integration tests on real CF runtime |

Infrastructure

| Service | Quota | Role | | :---------------- | :-------------------------------------------- | :---------------------------- | | Cloudflare D1 | 5M reads/day, 100k writes/day (Pro) | Primary relational database | | Cloudflare KV | 10M reads/day (Pro) | JWT cache + slot availability | | Cloudflare Queues | — | Async job dispatch | | Contentful | 100k API calls/mo, 50GB CDN (Free) | All CMS content | | Firebase Auth | Usage-based | Identity + JWT issuance | | Amazon SES | ~62k emails/mo free tier; $0.10/1k after | Primary transactional email | | Resend | 50k emails/mo (Pro) | Fallback transactional email |

Caching Strategy

Three Cloudflare cache tiers keep D1/Firebase within quota at 30k concurrent users:

| Tier | TTL | What it caches | | :------------ | :----- | :------------------------------ | | CF CDN Edge | 7 days | GET /events list (ETag-gated) | | CF KV | 3,600s | Firebase JWT tokens | | CF KV | 5s | Slot availability per event |

Auth

All users must sign in with @dlsu.edu.ph Google accounts. The backend rejects any other domain with 403 DOMAIN_RESTRICTED.

| Role | Token | Access | | :------ | :---------------------------- | :------------------------ | | guest | None | Public endpoints only | | user | Firebase JWT (@dlsu.edu.ph) | Protected user endpoints | | admin | JWT + admin: true claim | Admin mutation endpoints |

Resilience at Scale

Firebase Auth (~50 QPS limit): JWTs are cached in Cloudflare KV with a 3,600s TTL — >90% of requests skip Firebase entirely.

Email (200–500ms send latency): All email jobs are pushed to a Cloudflare Queue. The HTTP response returns immediately (202 Accepted); the consumer worker sends via Amazon SES (primary). If SES returns a non-retryable error and RESEND_API_KEY is set, the job is retried via Resend before landing in the DLQ. If RESEND_API_KEY is not set, fallback is skipped and the job goes straight to the DLQ after SES exhausts its retries.

Why SES? SES supports 14 emails/second by default (vs. Resend's 10/s), has a native suppression list, and is significantly cheaper at high volumes ($0.10 per 1k). Resend is an optional fallback — configure it for a deliverability dashboard and better incident visibility, or omit RESEND_API_KEY to run SES-only.

Deployment

Leapify targets Cloudflare Workers (standalone) or Cloudflare Pages Functions (colocated). Configure wrangler.toml with D1, KV, Queue bindings and Worker secrets.

Standalone:

npm run build && wrangler deploy

npm module (inside your own repo):

wrangler deploy   # your consumer worker that imports leapify

See wrangler.toml.example and .dev.vars.example for the full config shape.