Delivery & Architecture Document - Cloudflare Course App¶

1. System Architecture Overview¶

Project Concept: A decoupled Full-Stack Web Application built with an edge-caching frontend (Next.js) and an API-first backend (FastAPI). The architecture incorporates an S3-Compatible Object Storage (Cloudflare R2) and PostgreSQL (via SQLAlchemy).

1.1 High-Level Component View¶

Client (Frontend): Next.js 14+ (App Router), deployed on Cloudflare Pages. Features Tailwind CSS for styling and TanStack Query for optimal asynchronous state/cache management.
Server (Backend): Python FastAPI handling business logic, database queries, and generating S3-signed URLs for direct media uploads. Deployed natively or wrapped via WSGI/ASGI adapters on minimal managed infrastructure.
Database (Persistence): PostgreSQL instance accessed via SQLAlchemy ORM utilizing Alembic for schema migrations. Potential providers: Supabase, Neon.
Storage (Media Hub): Cloudflare R2 supporting CORS-enabled direct object uploads. Reduces server bandwidth latency drastically.

2. Infrastructure & Deployment Strategy¶

Frontend Hosting: Cloudflare Pages built directly from GitHub repository. Automated deployments triggered purely upon main branch pushes.
Backend Hosting: Platform-as-a-Service (PaaS) to run containerized FastAPI instances, e.g., Render, Railway, DigitalOcean Droplets, or specifically Cloudflare Workers if Python AST / DB driver limitations are resolved with alternative drivers (asyncpg or HTTP based query APIs like Supabase PostgREST).
Database Hosting: Supabase/Neon PostgreSQL cluster (using Transaction Pooling via port 6543 for serverless/edge environments).

2.1 Branching Strategy (Git Flow / CI/CD)¶

main/master: Production-ready codebase.
dev/staging: Active integration branch.
feature/{name}: Individual features merged into the active dev via Pull Requests.
Environment Variables: Handled separately between Local (.env.local), Staging, and Production (using Cloudflare/PaaS Secrets Managers).

3. Technology Stack specifics¶

Frontend:
Framework: Next.js (React)
Data Fetching: TanStack Query (React Query)
CSS Framework: Tailwind CSS v3/v4 (Custom UI Components)
Type-checking: TypeScript
Backend:
Framework: FastAPI, Uvicorn
Database Engine: PostgreSQL, SQLModel / SQLAlchemy
Migrations: Alembic
Cloud SDK: Boto3 (for S3 Cloudflare Object interaction)
Schemas: Pydantic v2

4. Work Breakdown Structure (WBS) & Deliverables¶

The project can be executed through Agile Sprints.

Sprint 1: Architecture & Foundation Setup * Deliverable: Monorepo Setup (Frontend/Backend). * Deliverable: PostgreSQL connected locally via SQLAlchemy. * Deliverable: Initial Alembic Migrations (Course model created). * Deliverable: Core RESTful endpoints established (GET/POST Courses).

Sprint 2: Media Storage & Business Logic * Deliverable: Configure Cloudflare R2 Buckets & CORS policies. * Deliverable: Boto3 implementation to parse presigned S3 URLs on the backend. * Deliverable: Frontend Client script built to directly PUT blobs to the generated presigned URLs securely. * Deliverable: Form Validation handling content metadata saving.

Sprint 3: UI/UX Master Polish * Deliverable: Visual redesign phase prioritizing immediate visual feedback and transitions. * Deliverable: Overhaul visual cards (hover, gradients, layouts) applying High-End aesthetic. * Deliverable: Loading Indicators (Top-bar NProgress or Next.js Loading states) optimized for no-lag experience.

Sprint 4: Deployment & Review * Deliverable: Frontend mapping correctly against the live Cloudflare Pages build hook. * Deliverable: Backend integration tested End-to-End against DB Provider (e.g. Supabase).

5. Security & Authentication Considerations¶

Role-Based Access Control (RBAC): To be implemented defining read-only vs. creator roles.
Upload Boundaries: Limit file sizes from the S3 pre-signer (generate conditions in boto3) restricting massive payload spam.
Rate-limiting: Protect Backend routes generating presigned URLs against excessive scraping or brute force.

6. Team Structure & Roles¶

Scrum Master / PM: Managing Sprints and Backlog.
Full-Stack Developers: Next.js + FastAPI implementation.
DevOps Engineer: Managing CI/CD Pipeline, CF Pages / DNS, and PaaS DB provisioning.
Business Analyst: Verifying feature completion against documentation criteria.

7. Technical Debt & Mitigation Strategy¶

7.1 Identified Tech Debt & Known Limitations¶

Edge Deployment Discrepancy (Backend): Due to standard Python ORM (SQLAlchemy) reliance on synchronous database drivers (psycopg2) and lack of robust AST support in Cloudflare Workers for raw Python frameworks, the backend currently requires deployment via traditional PaaS (Render/DigitalOcean) instead of residing directly on Cloudflare Edge alongside the Frontend.
Orphaned Media Files: Users aborting a course creation midway leave S3/R2 files that have been uploaded via presigned URLs untouched but never successfully mapped into the persistent PostgreSQL database, causing steady storage bloat.
Database Schema Tight-Coupling: The current SQLAlchemy configurations might require heavy refactoring if migrating towards a document-storage approach or expanding fields rapidly without downtime.
Lack of Automated E2E Testing: Rapid MVP deployment limits our frontend testing scope to unit tests, deferring full UI automation (Playwright/Cypress).

7.2 Mitigation Roadmap¶

Refactoring Backend to Edge (Phase 2): Investigate Cloudflare Hyperdrive integration for global database pooling or transition SQL/ORM layers pointing to Supabase Edge Functions with postgrest-py to natively achieve complete severless architecture on CF infrastructure.
Garbage Collection Service (Cron): Build a recurring background task (Cloudflare Scheduled Worker) that cross-references the state of R2 buckets against Course.image_url / Course.video_url. Delete any objects older than 24 hours lacking a valid database parent.
Dedicated Q/A Sprint (Sprint 5): A follow-up sprint focused purely on resolving technical debt by establishing GitHub Actions for automated API testing via Postman/Newman and UI workflows via Cypress.