Skip to content

Feature Planning Document: Deploy Checkin App to Cloudflare

1. Executive Summary & Feature Overview

1.1 Feature Description

  • Feature Name: Cloudflare Pages Deployment for Checkin Application
  • Feature Type: Infrastructure Enhancement / Deployment
  • Priority Level: High

1.2 Problem Statement

  • Current State: The checkin app is a Vite-based React application that currently only has a CI build test workflow but no automated deployment pipeline.
  • Pain Points:
  • Manual deployment process (if any)
  • No staging/production environment separation
  • Lack of consistent deployment infrastructure compared to the frontend app
  • User Impact: Event staff and administrators who need reliable access to the checkin application
  • Business Value:
  • Automated, reliable deployments
  • Reduced deployment friction and human error
  • Consistent infrastructure across all PiqueTickets applications
  • Improved availability and performance via Cloudflare's edge network

1.3 Expected Outcomes

  • Success Metrics:
  • Automated deployments on push to main (production) and stage branches
  • Build and deployment time under 5 minutes
  • Zero-downtime deployments
  • Successful environment variable injection
  • User Experience Goals:
  • Fast, global access to checkin app via Cloudflare's CDN
  • Seamless updates without service interruption
  • Technical Goals:
  • Replicate frontend deployment pattern for consistency
  • Support both staging and production environments
  • Proper environment variable management for API endpoints

2. Stakeholder Analysis & Requirements

2.1 Affected Users & Systems

  • Primary Users: Event staff, venue managers using the checkin app
  • Secondary Users: DevOps team managing deployments, developers pushing changes
  • System Components:
  • Checkin app (Vite/React SPA)
  • Django API backend (for checkin endpoints)
  • Cloudflare Pages infrastructure
  • GitHub Actions CI/CD pipeline
  • Integration Points:
  • Django API at VITE_API_ENDPOINT
  • Cloudflare Workers/Pages
  • GitHub repository

2.2 Functional Requirements

Must-Have Features: - Wrangler configuration file for Cloudflare Pages deployment - GitHub Actions workflow for automated deployment - Separate staging and production environments - Environment variable management (VITE_API_ENDPOINT) - Build artifact optimization

Should-Have Features: - Manual deployment trigger via workflow_dispatch - Deployment status notifications - Rollback capability

Could-Have Features: - Preview deployments for pull requests - Deployment metrics/analytics - Custom domain configuration

Won't-Have Features: - Server-side rendering (this is a static SPA) - Edge functions (not needed for this use case)

2.3 Non-Functional Requirements

Performance: - Build time: < 3 minutes - Deployment time: < 2 minutes - Page load time: < 2 seconds (via Cloudflare CDN)

Security: - Secure API token management via GitHub Secrets - Environment variable encryption - HTTPS enforcement

Accessibility: - No changes to app accessibility (deployment only)

Browser/Platform Support: - Same as existing checkin app requirements

Reliability: - 99.9% uptime target (Cloudflare SLA) - Automated health checks - Deployment failure notifications

3. Current State Analysis

3.1 Codebase Research Methodology

Primary Tools: - Serena MCP - Code exploration and pattern matching - mcp__serena__find_file - Located wrangler.toml in docs/, GitHub workflows in .github/workflows/ - mcp__serena__search_for_pattern - Found all cloudflare/wrangler usages in workflows - mcp__serena__list_dir - Explored apps structure, checkin app directory structure - mcp__serena__read_memory - Retrieved project overview for context - Standard Read tool - Examined configuration files in detail: - .github/workflows/deploy-cloudflare.yml - Frontend deployment pattern - .github/workflows/checkin-build.yml - Existing checkin build test - apps/frontend/package.json - Frontend build scripts and dependencies - apps/checkin/package.json - Checkin app dependencies - apps/checkin/vite.config.ts - Vite build configuration - apps/checkin/.env - Environment variable structure

Key Findings: - Frontend uses OpenNext.js for Cloudflare Workers deployment - Checkin app is a standard Vite/React SPA (simpler deployment model) - Existing build workflow at .github/workflows/checkin-build.yml only runs on PRs - No wrangler configuration exists for checkin app - Environment variables use VITE_ prefix

3.2 Existing Architecture & Patterns

Tech Stack: - Checkin App: - Vite 6.4.1 (build tool) - React 18.2.0 + React DOM - TypeScript 5.2.2 - React Router DOM 6.22.1 - Axios 1.12.0 (API calls) - @zxing/browser & @zxing/library (QR code scanning)

  • Build Output: Static files (HTML, CSS, JS) in dist/ directory

Architecture Pattern: - Single Page Application (SPA) - Client-side routing with React Router - API integration via Axios to Django backend

Design Patterns: - Component-based React architecture - Service layer for API calls (services/api.ts) - Environment variable configuration

Code Organization: 

apps/checkin/
├── src/
│   ├── components/     # React components
│   ├── pages/          # Page components
│   ├── services/       # API service layer
│   ├── types/          # TypeScript types
│   ├── App.tsx         # Main app component
│   └── main.tsx        # Entry point
├── index.html          # HTML template
├── vite.config.ts      # Vite configuration
└── package.json        # Dependencies and scripts

Data Flow: - User interacts with checkin UI - API calls via Axios to Django backend (VITE_API_ENDPOINT) - Responses rendered in React components

3.3 Relevant Existing Code

Discovery Method: Used Serena MCP find_file and Read tool to examine deployment patterns.

Similar Features:

  1. Frontend Cloudflare Deployment (.github/workflows/deploy-cloudflare.yml:1)
  2. Pattern: Separate jobs for stage and production
  3. Uses npx wrangler deploy with environment flags
  4. Injects build-time environment variables

  5. Uses GitHub secrets for CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID

  6. Docs Deployment (.github/workflows/deploy-docs.yml:1)

  7. Pattern: Uses wrangler pages deploy
  8. References wrangler.toml configuration
  9. Simpler static site deployment model

Reusable Components: - GitHub Actions workflow structure from deploy-cloudflare.yml - Wrangler configuration pattern from docs/wrangler.toml - Build caching strategy from existing workflows - Environment management approach

Shared Utilities: - Wrangler CLI (already in frontend dependencies) - GitHub Actions actions (checkout@v4, setup-node@v4)

Integration Points: - Django API endpoints (/api/v1/checkin/) - Cloudflare account infrastructure

3.4 Current Dependencies

Core Dependencies (apps/checkin/package.json:12-22): - React 18.2.0 + React DOM - React Router DOM 6.22.1 - Axios 1.12.0 - @zxing/browser & @zxing/library (QR scanning) - qrcode.react 4.2.0

Development Dependencies (apps/checkin/package.json:24-35): - Vite 6.4.1 - TypeScript 5.2.2 - @vitejs/plugin-react 4.2.1 - ESLint + TypeScript ESLint

New Dependencies Needed: - wrangler (for Cloudflare Pages deployment) - Can be used via npx or added to devDependencies

Infrastructure Dependencies: - Cloudflare account - GitHub repository - GitHub Secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID

3.5 Potential Conflicts & Constraints

Technical Debt: - None identified for this deployment task

Legacy Code: - Environment variable in .env points to localhost - needs separate stage/prod configs

Resource Constraints: - Cloudflare Pages free tier limits (500 builds/month, 100GB bandwidth/month) - GitHub Actions runner minutes

Compliance Requirements: - Same as existing PiqueTickets applications

4. Research & Best Practices

4.1 Industry Standards Research

Research Sources: Cloudflare Pages documentation, Vite deployment guides, GitHub Actions best practices

Cloudflare Pages Best Practices: - Use wrangler pages deploy for static sites - Configure build output directory in wrangler.toml - Use environment variables for different deployment targets - Leverage preview deployments for PR testing

Vite Production Build Best Practices: - Run vite build to generate optimized production bundle - Output goes to dist/ directory by default - Environment variables must be prefixed with VITE_ to be exposed - Use --mode flag for different build configurations

GitHub Actions Best Practices: - Cache npm dependencies for faster builds - Use environment protection rules for production - Separate staging and production jobs - Use workflow_dispatch for manual deployments

Codebase Pattern Validation: - Existing frontend deployment follows Cloudflare + GitHub Actions pattern ✅ - Checkin app uses standard Vite build process ✅ - Environment variable naming follows Vite conventions ✅

4.2 Framework/Library Research

Vite Documentation: - Building for Production - Default output: dist/ - Optimizes CSS, JS, and assets automatically - Supports environment-specific builds via --mode

Cloudflare Pages Documentation: - Deploying with Wrangler - Framework guides - Vite - wrangler.toml configuration for Pages projects

Wrangler CLI: - wrangler pages deploy <directory> for deployment - --project-name to specify Pages project - Environment variables via wrangler.toml or dashboard

4.3 Case Studies & Examples

Similar Implementations: - Frontend app deployment (.github/workflows/deploy-cloudflare.yml) - uses Workers with OpenNext.js - Docs deployment (.github/workflows/deploy-docs.yml) - uses Pages (more similar to our use case)

Lessons Learned: - Cloudflare Pages is simpler for static SPAs than Workers - Use pages deploy not just deploy for Pages projects - Environment variables need to be set at build time for Vite apps - Separate wrangler.toml files can coexist in monorepo subdirectories

5. Solution Design

5.1 Proposed Architecture

Design Validation: Pattern follows existing docs deployment (Pages) rather than frontend deployment (Workers).

High-Level Design:

┌─────────────────┐
│  GitHub Repo    │
│  (main/stage)   │
└────────┬────────┘
         │ Push event
         ▼
┌─────────────────────────────────────┐
│   GitHub Actions Workflow           │
│                                     │
│  1. Checkout code                   │
│  2. Setup Node.js + cache           │
│  3. npm ci (install deps)           │
│  4. npm run build (Vite)            │
│  5. Inject env vars                 │
│  6. wrangler pages deploy dist/     │
└────────┬────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│   Cloudflare Pages                  │
│                                     │
│  Stage:       checkin-stage         │
│  Production:  checkin-production    │
│                                     │
│  Served via Cloudflare CDN          │
└─────────────────────────────────────┘

Data Model Changes: - None (deployment only)

API Design: - No API changes - Checkin app continues to call Django API at VITE_API_ENDPOINT

Configuration Files to Create:

  1. apps/checkin/wrangler.toml (New File) 

    name = "piquetickets-checkin"
pages_build_output_dir = "dist"
compatibility_date = "2024-01-01"

  2. .github/workflows/deploy-checkin.yml (New File) Structure based on deploy-cloudflare.yml pattern with modifications for Pages deployment

Integration Strategy: - Follows existing deployment pattern from frontend - Uses same GitHub secrets (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID) - Separate workflow file for clarity and independent deployment - Uses Pages instead of Workers (simpler for SPA)

5.2 Technology Decisions

New Dependencies: - wrangler - Added as devDependency in apps/checkin/package.json - Justification: Required for Cloudflare Pages deployment - Version: ^4.45.0 (matches frontend version)

Alternative Solutions Considered:

  1. Cloudflare Workers (like frontend)
  2. ❌ Overkill for simple SPA
  3. ❌ Requires OpenNext.js or similar adapter

  4. ✅ Used by frontend but frontend needs SSR capabilities

  5. Cloudflare Pages (SELECTED)

  6. ✅ Perfect for static SPAs
  7. ✅ Simpler configuration
  8. ✅ Free tier generous

  9. ✅ Built-in preview deployments

  10. Other hosting (Vercel, Netlify, etc.)

  11. ❌ Introduces inconsistency (frontend on Cloudflare)
  12. ❌ Additional vendor management

Proof of Concepts: - Not needed - well-established pattern

5.3 Security Considerations

Threat Model: - Exposure of API endpoints in client-side code (already exists, acceptable for public API) - Unauthorized deployment access (mitigated via GitHub secrets)

Authentication/Authorization: - Cloudflare API token stored as GitHub secret - GitHub environment protection rules for production

Data Protection: - Environment variables encrypted in GitHub Secrets - HTTPS enforced by Cloudflare - No sensitive data in checkin app itself (handled by API)

Security Testing: - No changes to app security posture - Deployment process uses industry-standard secured CI/CD

6. Implementation Plan

6.1 Development Phases

Phase 1: Configuration Setup - [ ] Create apps/checkin/wrangler.toml configuration file - [ ] Add wrangler to apps/checkin/package.json devDependencies - [ ] Create environment variable templates for stage/production - [ ] Deliverable: Configuration files ready for deployment

Phase 2: GitHub Actions Workflow - [ ] Create .github/workflows/deploy-checkin.yml - [ ] Configure stage deployment job - [ ] Configure production deployment job - [ ] Add environment variable injection - [ ] Test workflow with dry-run - [ ] Deliverable: Working deployment workflow

Phase 3: Cloudflare Setup & Testing - [ ] Create Cloudflare Pages projects (stage and production) - [ ] Verify GitHub secrets are configured - [ ] Test stage deployment - [ ] Test production deployment - [ ] Configure custom domains (if needed) - [ ] Deliverable: Live deployments on both environments

6.2 Detailed Task Breakdown

Task Files Affected Dependencies Assignee
Create wrangler.toml apps/checkin/wrangler.toml None TBD
Add wrangler dependency apps/checkin/package.json None TBD
Create deploy workflow .github/workflows/deploy-checkin.yml wrangler.toml TBD
Set up Cloudflare Projects Cloudflare Dashboard None TBD
Configure GitHub Secrets GitHub Repository Settings Cloudflare setup TBD
Test stage deployment All above All above TBD
Test production deployment All above Stage test passing TBD
Update documentation apps/checkin/README.md Successful deploy TBD

6.3 File Change Summary

New Files:

  1. apps/checkin/wrangler.toml - Cloudflare Pages configuration
  2. Purpose: Define Pages project settings, output directory

  3. Pattern Reference: Similar to docs/wrangler.toml

  4. .github/workflows/deploy-checkin.yml - Deployment workflow

  5. Purpose: Automate builds and deployments to Cloudflare Pages
  6. Pattern Reference: Based on deploy-cloudflare.yml and deploy-docs.yml

Modified Files:

  1. apps/checkin/package.json - Add wrangler to devDependencies
  2. Changes: Add "wrangler": "^4.45.0" to devDependencies

  3. Impact: Development and CI environments can run wrangler commands

  4. apps/checkin/README.md - Document deployment process (if exists, or create)

  5. Changes: Add deployment instructions and environment information
  6. Usage: Team documentation

Deleted Files: - None

7. Testing Strategy

7.1 Test Coverage Plan

Deployment Testing: - [ ] Verify stage deployment completes successfully - [ ] Verify production deployment completes successfully - [ ] Test manual workflow_dispatch trigger - [ ] Verify environment variables are correctly injected - [ ] Test API connectivity from deployed app - [ ] Verify asset optimization and loading

Integration Testing: - [ ] Checkin app connects to correct API endpoint (stage/prod) - [ ] QR scanning functionality works in deployed environment - [ ] Browser compatibility across major browsers - [ ] Mobile responsiveness on deployed site

Regression Testing: - [ ] Existing functionality unaffected - [ ] No broken routes or components - [ ] API integration still functional

7.2 Test Environment Requirements

Development: - Local Vite dev server (existing) - Access to stage API endpoint

Staging: - Cloudflare Pages stage project - Stage API endpoint: https://piquetickets-django-stage.up.railway.app/api/v1/checkin/ (assumed) - URL: TBD (e.g., checkin-stage.piquetickets.com)

Production: - Cloudflare Pages production project - Production API endpoint: TBD - URL: TBD (e.g., checkin.piquetickets.com)

7.3 Acceptance Criteria

Definition of Done: - [ ] Wrangler configuration created and committed - [ ] GitHub Actions workflow created and functional - [ ] Stage environment deployed and accessible - [ ] Production environment deployed and accessible - [ ] Environment variables correctly configured for both environments - [ ] Checkin app successfully communicates with Django API in both environments - [ ] Build completes in under 5 minutes - [ ] Deployment completes in under 2 minutes - [ ] Documentation updated - [ ] Team notified of new deployment process

8. Risk Assessment & Mitigation

8.1 Technical Risks

Risk Probability Impact Mitigation Strategy
Build failures due to environment variable issues Medium High Test thoroughly in stage first; validate env var injection
API CORS issues from new domain Medium High Coordinate with backend team to whitelist new domains
Cloudflare Pages quota exceeded Low Medium Monitor usage; upgrade plan if needed
Asset loading failures (paths) Low Medium Verify base path configuration in Vite config
Deployment token expiration Low High Document token refresh process; set calendar reminders

8.2 Resource Risks

Schedule Risks: - Cloudflare account setup delays - Mitigate by starting early - GitHub secrets configuration access - Coordinate with repo admins

Skill Gaps: - Team unfamiliarity with Cloudflare Pages - Provide documentation and training

External Dependencies: - Cloudflare service availability - Use Cloudflare status page monitoring - GitHub Actions availability - Minimal risk, industry-standard platform

8.3 Rollback Strategy

Cloudflare Pages: - Native rollback to previous deployment via Cloudflare dashboard - Each deployment preserved in Cloudflare history - One-click rollback capability

GitHub Workflow: - Disable workflow temporarily via GitHub UI if issues arise - Revert workflow file commit if needed

Emergency Procedure: 1. Identify issue (monitoring/alerts) 2. Rollback to previous deployment in Cloudflare dashboard 3. Investigate root cause 4. Fix and redeploy or keep rolled back 5. Post-mortem documentation

9. Deployment & Operations

9.1 Deployment Plan

Environment Progression:

  1. Initial Setup:
  2. Create Cloudflare Pages projects (stage, production)
  3. Configure GitHub secrets

  4. Merge wrangler.toml and package.json changes

  5. Stage Deployment:

  6. Push to stage branch or manual trigger
  7. GitHub Actions builds and deploys to stage

  8. Validate functionality

  9. Production Deployment:

  10. Push to main branch or manual trigger
  11. GitHub Actions builds and deploys to production
  12. Monitor for issues

Configuration Updates: - Environment variables managed via GitHub Secrets - No runtime configuration (build-time injection)

Monitoring Setup: - Cloudflare Pages analytics (built-in) - GitHub Actions workflow status notifications - Optional: Custom alerting for deployment failures

9.2 Monitoring & Observability

Key Metrics: - Build success/failure rate - Deployment duration - Page load times (Cloudflare Analytics) - API request success rate (from app) - Error rates (browser console errors)

Alerting: - GitHub Actions failure notifications (email) - Optional: Slack/Discord webhook integration - Cloudflare status notifications

Logging: - GitHub Actions build logs - Browser console (client-side errors) - Django API logs for backend issues

Health Checks: - Cloudflare Pages automatic health monitoring - Manual smoke tests post-deployment

9.3 Support & Maintenance

Documentation: - Update apps/checkin/README.md with deployment instructions - Document environment variable management - Create runbook for common deployment issues

Training: - Team walkthrough of new deployment process - Document rollback procedures

Ongoing Maintenance: - Monitor Cloudflare usage against quotas - Periodic review of build optimization - Update wrangler and dependencies as needed - Rotate API tokens annually (security best practice)

10. Success Measurement

10.1 Success Metrics

Technical Metrics: - Build time: Target < 3 minutes (Baseline: TBD after first deployment) - Deployment time: Target < 2 minutes - Zero deployment failures in first month - Page load time: < 2 seconds globally (Cloudflare CDN benefit)

User Metrics: - No user-reported issues related to deployment - Improved availability (target 99.9%)

Business Metrics: - Reduced manual deployment effort (automation) - Faster time to production for checkin app updates - Consistency with other app deployments

10.2 Review Schedule

  • Initial Review: 1 week after production deployment
  • Check deployment stability
  • Review any issues encountered

  • Gather team feedback

  • Monthly Review: Ongoing

  • Monitor usage and costs
  • Review build performance
  • Optimize as needed

11. Appendices

Appendix A: Research References

Appendix B: Technical Diagrams

Deployment Flow: 

Developer Push (main/stage)
        ↓
GitHub Actions Triggered
        ↓
    Checkout Code
        ↓
  Install Dependencies
        ↓
   Vite Build (dist/)
        ↓
 Inject Environment Vars
        ↓
  Wrangler Pages Deploy
        ↓
Cloudflare Pages (Stage/Prod)
        ↓
   Global CDN Distribution

Architecture: 

┌────────────────────────────────────────────────┐
│            Cloudflare Pages                    │
│  ┌──────────────────┐  ┌──────────────────┐   │
│  │  Stage           │  │  Production      │   │
│  │  checkin-stage   │  │  checkin-prod    │   │
│  └────────┬─────────┘  └────────┬─────────┘   │
│           │                     │              │
└───────────┼─────────────────────┼──────────────┘
            │                     │
            ▼                     ▼
      Stage API             Production API
  (Django Backend)        (Django Backend)

Appendix C: Code Examples

Wrangler Configuration (apps/checkin/wrangler.toml): 

name = "piquetickets-checkin"
pages_build_output_dir = "dist"
compatibility_date = "2024-01-01"

GitHub Workflow (excerpt): 

- name: Build application
  working-directory: apps/checkin
  run: npm run build
  env:
    VITE_API_ENDPOINT: ${{ secrets.VITE_API_ENDPOINT_STAGE }}

- name: Deploy to Cloudflare Pages
  working-directory: apps/checkin
  run: npx wrangler pages deploy dist --project-name=piquetickets-checkin-stage
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Package.json Addition: 

{
  "devDependencies": {
    "wrangler": "^4.45.0"
  }
}

Appendix D: Environment Variables

Required GitHub Secrets: - CLOUDFLARE_API_TOKEN - API token with Pages deploy permission (already exists) - CLOUDFLARE_ACCOUNT_ID - Cloudflare account ID (already exists) - VITE_API_ENDPOINT_STAGE - Stage API URL (new) - VITE_API_ENDPOINT_PRODUCTION - Production API URL (new)

Checkin App Environment Variables: - VITE_API_ENDPOINT - Injected at build time from GitHub secrets

Document Information

  • Created: 2025-11-07
  • Last Updated: 2025-11-07
  • Version: 1.0
  • Author(s): Claude Code
  • Reviewers: TBD
  • Status: Draft

Quick Checklist for Implementation

Pre-Implementation

  • Review and approve this planning document
  • Identify API endpoint URLs for stage and production
  • Verify Cloudflare account access and permissions
  • Verify GitHub secrets are configured or can be added
  • Determine custom domain names (if needed)

Implementation

  • Create apps/checkin/wrangler.toml
  • Update apps/checkin/package.json with wrangler
  • Create .github/workflows/deploy-checkin.yml
  • Set up Cloudflare Pages projects
  • Add GitHub secrets for API endpoints
  • Test stage deployment
  • Test production deployment
  • Update documentation

Post-Implementation

  • Monitor first week of deployments
  • Gather team feedback
  • Document any issues and resolutions
  • Schedule review meeting