How lubomirgeorgiev/cloudflare-workers-nextjs-saas-template works
Main Components
• Frontend UI & Routing Layer – Represented by the “src/app” folder, which is segmented into various functional parts such as authentication ((auth) subdirectory), dashboard (marketplace, billing, settings, etc.), legal, and marketing pages. This component uses Next.js (server components, React components) along with modern UI technologies (Tailwind CSS, shadcn/ui).
• Backend API & Actions – API endpoints and action files are distributed in “src/app/api” and “src/actions”. This includes session handling, authentication actions, and billing operations.
• Authentication Module – Look at the “src/app/(auth)” and associated client and server action files. This module integrates several authentication strategies (email/password, passkey, OAuth through Google) and manages workflows like password resets and email verification.
• Database Layer – Found under “src/db” and “drizzle.config.ts”, this component handles migrations, schema definitions, and the communication with the Cloudflare D1 database in production (and SQLite for local development) with a type-safe interface.
• Email Service – Under “src/react-email”, the project has built-in email templates for actions like password reset and email verification. It interfaces with external providers like Resend or Brevo.
• Payment/Billing Component – Within “src/app/(dashboard)/dashboard/billing” and related scripts, the application integrates credit billing functionality using Stripe along with client components for payment forms and transaction histories.
• External Integrations & Edge Services – This includes the Cloudflare Workers deployment (guided by “wrangler.jsonc” and deployment scripts in “.github/workflows/”) and session storage using Cloudflare KV, as well as rate limiting and other security measures.
• Utility Libraries & Services – Modules for handling shared business logic (in “src/lib”, “src/utils”, “src/schemas”, “src/hooks”) which underpin authentication, session management, and API interactions.
Relationships and Interactions
• The user interacts with the Frontend UI, which routes them to different parts of the application (auth, dashboard, marketing, settings).
• When a user performs an action (e.g., sign-in, sign-up, purchase, or email verification), the frontend issues requests to the backend API endpoints.
• The Backend API coordinates with multiple services/components: it authenticates requests, performs business logic (e.g., billing, session management), interacts with the database for persistent storage (using Drizzle and migrations), and handles external integrations (e.g., contacting the email service or Stripe).
• Cloudflare Workers host the entire application deployment, ensuring global edge delivery, zero cold starts, and handling tasks like KV session storage, API routing, and rate limiting.
Architectural Patterns & Design Principles
• Separation of Concerns – The file structure clearly segregates responsibilities (UI components, API actions, authentication workflows, database interactions).
• Modular Architecture – Components such as authentication, billing, and email services are self-contained, making extensions or modifications straightforward.
• Edge-first Deployment – Leveraging Cloudflare Workers and KV storage ensures low latency and high scalability.
• Type-Safety and Validation – The use of TypeScript, Zod schemas, and Drizzle’s type-safe queries ensures that data and logic are robustly validated.
• CI/CD Integration – Automated deployments via GitHub Actions (as evident from the GitHub workflows) enforce a strong DevOps pipeline.