E-commerce Store (Bakery Platform)

Build and manage a full-stack e-commerce bakery platform (Sweet Angel Bakery) on Cloudflare Workers with Next.js 15. Includes customer storefront, admin management, delivery tracking, loyalty program, and Square/Stripe payment processing.

Tech Stack

**Frontend**: Next.js 15 (App Router) • React 19 • TypeScript • Tailwind CSS 4 • Shadcn UI

**Backend**: Cloudflare Workers (OpenNext) • Drizzle ORM • D1 Database

**Payments**: Square/Stripe (abstracted provider pattern)

**Auth**: Email/password, WebAuthn, Google OAuth, Magic links

**Email**: React Email with Resend or Brevo

Architecture Overview

Route Structure

`(auth)/*` - Authentication flows (email/password, WebAuthn, Google OAuth)

`(storefront)/*` - Customer-facing pages (products, cart, checkout, loyalty)

`(admin)/admin/*` - Admin dashboard (orders, products, users, analytics)

`(settings)/settings/*` - User profile and session management

`(legal)/*` - Terms, privacy policy

`api/*` - API routes, webhooks, image uploads

Key Patterns

**Merchant Provider Abstraction**: Payment processor abstraction in `src/lib/merchant-provider/`. Factory pattern dynamically selects Square or Stripe. To add new provider, implement interface in `providers/` and update factory.

**Type-Safe Server Actions (ZSA)**: All server operations use `createServerAction()` with Zod validation. Actions co-located in `*.actions.ts` files.

**Session Storage**: Sessions stored in Cloudflare KV (not D1) for edge performance. Max 5 sessions/user, 30-day expiration.

**Delivery System**: Timezone-aware delivery dates, route optimization with Google Maps, ETA tracking.

**Product Customizations**: Flexible addon system with price adjustments stored as JSON in order items.

Essential Commands

Development

```bash

pnpm dev # Start dev server (localhost:3000)

pnpm db:migrate:dev # Apply migrations to local SQLite

pnpm db:studio # Open Drizzle Studio (visual DB explorer)

pnpm email:dev # Preview email templates (localhost:3001)

```

Database Management

```bash

pnpm db:generate [NAME] # Generate migration from schema changes

pnpm db:migrate:prod # Apply migrations to production D1

```

Build & Deploy

```bash

pnpm build # Next.js build

pnpm deploy # Build with OpenNext + deploy to Cloudflare

pnpm cf-typegen # Generate Cloudflare binding types

```

Utilities

```bash

pnpm scrape:products # Scrape products from external source

pnpm sync:square # Sync with Square API

pnpm import:square # Import products from Square

```

Instructions for AI Agent

1. Code Conventions

**General Rules**:

Use functional components with TypeScript (no classes)

Server Components by default; add `"use client"` only when needed

Add `import "server-only"` at top of server-only files (except `page.tsx`)

Functions with >1 parameter: use named object pattern `function foo({ a, b }) {}`

Never delete existing comments unless clearly irrelevant

Always use `pnpm` for package management

**Imports**:

Check `package.json` before adding new packages to avoid duplicates

Use `@/*` path alias for imports

Server actions: `import { useServerAction } from "zsa-react"`

**State Management**:

Server state: React Server Components

Client state: Zustand stores in `src/state/`

URL state: NUQS

Forms: React Hook Form + Zod validation

**Styling**:

Tailwind CSS 4 with Shadcn UI components (`src/components/ui/`)

Dark/light mode via next-themes

2. Database Operations (Drizzle ORM)

**Critical Rules**:

**Never pass `id` to `.insert().values()` or `.update()` calls** (auto-generated CUID2)

**Never use Drizzle transactions** (D1 doesn't support them)

Schema location: `src/db/schema.ts` (21+ tables)

**Database Access Pattern**:

```typescript

const db = getDB(); // Cached via React cache()

await db.query.userTable.findFirst({ where: eq(...) });

```

**Migration Workflow**:

1. Edit `src/db/schema.ts`

2. Run `pnpm db:generate migration-name`

3. Apply: `pnpm db:migrate:dev` (local) or `pnpm db:migrate:prod` (production)

3. Authentication

**Session Access**:

**Server Components**: Use `getSessionFromCookie()` from `src/utils/auth.ts`

**Client Components**: Use `useSessionStore()` from `src/state/session.ts`

**Key Files**:

`src/utils/auth.ts` - Session creation/validation

`src/utils/kv-session.ts` - KV storage logic

`src/lib/sso/google-sso.ts` - Google OAuth setup

4. Cloudflare Bindings

**Bindings in `wrangler.jsonc`**:

`NEXT_TAG_CACHE_D1` - D1 database for tag-based cache

`NEXT_INC_CACHE_KV` - KV for incremental cache (ISR)

`PRODUCT_IMAGES` - R2 bucket for images

`NEXT_CACHE_DO_QUEUE` - Durable Object for cache queue

**Important**: After editing `wrangler.jsonc`, always run `pnpm cf-typegen` to regenerate types.

5. Type Definitions

Add global types to `custom-env.d.ts` (not `cloudflare-env.d.ts` - gets overwritten by codegen)

Use TypeScript strictly with proper validation

6. Security & Performance

**Security**:

Turnstile CAPTCHA integration

Anti-disposable email validation

Input sanitization via Zod schemas

HMAC-SHA256 webhook verification (Square)

**Rate Limiting**:

IP-based via `withRateLimit()` decorator using Cloudflare KV

**Email Templates**:

React Email components in `src/react-email/`

Services: Resend or Brevo

7. Payment Processing

Use the merchant provider abstraction in `src/lib/merchant-provider/`. Never hardcode Square or Stripe logic directly - always go through the factory pattern for provider-agnostic code.

8. Environment Setup (First Time)

1. `pnpm install`

2. Copy `.dev.vars.example` → `.dev.vars` (Cloudflare credentials, API keys)

3. Copy `.env.example` → `.env` (public keys: Turnstile, Square, Stripe, Google OAuth)

4. `pnpm db:migrate:dev` - Create local database

5. `pnpm dev` - Start development server

9. Deployment

GitHub Actions CI/CD (`.github/workflows/deploy.yml`) triggers on push to `main`:

1. Install dependencies

2. Migrate local D1

3. `pnpm deploy` (OpenNext build + Cloudflare deploy)

4. Apply remote D1 migrations

5. Purge CDN cache

10. Important Notes

**No test suite**: Project uses Playwright for manual/browser testing only

**Webhook verification**: HMAC-SHA256 in `api/webhooks/square/route.ts`

**Scripts**: Product scraping and Square sync utilities in `scripts/`

**Product customizations schema**: `src/schemas/customizations.schema.ts`

**Timezone handling**: `src/utils/timezone.ts` for delivery date calculations

Example Usage

**Adding a new feature**:

1. Check existing patterns in route structure

2. Create server action in `*.actions.ts` with Zod validation

3. Use Server Components for data fetching

4. Add client interactivity with `"use client"` only where needed

5. Update database schema if needed (follow migration workflow)

6. Test locally with `pnpm dev` and Drizzle Studio

**Database changes**:

1. Edit `src/db/schema.ts`

2. `pnpm db:generate add-new-column`

3. `pnpm db:migrate:dev`

4. Deploy: `pnpm db:migrate:prod`

**Adding a new payment provider**:

1. Implement interface in `src/lib/merchant-provider/providers/new-provider.ts`

2. Update factory in `src/lib/merchant-provider/factory.ts`

3. Add provider-specific env vars to `.dev.vars` and `.env`

Constraints

Use `pnpm` exclusively (not npm or yarn)

Never use Drizzle transactions

Never pass `id` to database insert/update operations

Always run `pnpm cf-typegen` after modifying `wrangler.jsonc`

Add `"use server"` to server action files

Add `"use client"` only when client-side hooks/state needed

Preserve existing comments in code

Check `package.json` before adding dependencies

E-commerce Store (Bakery Platform)

E-commerce Store (Bakery Platform)

Tech Stack

Architecture Overview

Route Structure

Key Patterns

Essential Commands

Development

Database Management

Build & Deploy

Utilities

Instructions for AI Agent

1. Code Conventions

2. Database Operations (Drizzle ORM)

3. Authentication

4. Cloudflare Bindings

5. Type Definitions

6. Security & Performance

7. Payment Processing

8. Environment Setup (First Time)

9. Deployment

10. Important Notes

Example Usage

Constraints

Reviews (0)