Full-Stack E-Commerce SaaS with AI

Architect a production-grade e-commerce storefront with Zod-validated Server Actions, optimistic bag drawers, idempotent Stripe webhooks, cached AI catalog copy, and Core Web Vitals optimization.

6-Month Plan

Next.js App RouterReact 19Tailwind CSSPostgreSQL (Supabase)Stripe Checkout

System Architecture Data Flow

┌────────────────┐       ┌─────────────────┐       ┌────────────────┐
│ Next.js Client │ ────> │ Server Actions  │ ────> │  PostgreSQL    │
│  Optimistic UI │       │  (Zod + Auth)   │       │  (Products DB) │
└────────────────┘       └────────┬────────┘       └────────────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │ Stripe Webhook  │
                         │ (HMAC + Idemp.) │
                         └─────────────────┘

Prerequisites & Environment Setup

Node.js 20+ & npm/pnpm installed
DATABASE_URL (PostgreSQL / Supabase connection string)
STRIPE_SECRET_KEY & STRIPE_WEBHOOK_SECRET in server .env.local (never NEXT_PUBLIC_*)
Redis or PostgreSQL table for webhook event_id idempotency tracking

Phase 1: Project Scaffolding & Metadata Layout

Master AI Prompt (Copy into Cursor / Claude / Coding Agent)

Act as a Principal Next.js Architect. Generate a production-ready Next.js App Router project structure with TypeScript and Tailwind CSS. Include: - Clean directory layout: app/, components/, lib/, actions/ - Strict TypeScript tsconfig.json with path aliases (@/*) - A semantic layout.tsx with dark-mode typography and canonical metadata.

Production Reference Code

// app/layout.tsx
import './globals.css';
import { Inter } from 'next/font/google';

const inter = Inter({ subsets: ['latin'], display: 'swap' });

export const metadata = {
  title: 'Aura Storefront — High-Performance E-Commerce',
  description: 'Production Next.js storefront with sub-second LCP and zero layout shift.',
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className="dark">
      <body className={`${inter.className} bg-background text-foreground antialiased`}>
        {children}
      </body>
    </html>
  );
}

Smoke Verification & Tests

Run `stripe listen --forward-to localhost:3000/api/webhooks/stripe` and verify duplicate webhook replay returns 200 without double-fulfilling orders.
Submit invalid UUID to Server Action and confirm Zod rejects before hitting PostgreSQL.
Run Lighthouse CI / Core Web Vitals check and verify LCP < 2.5s and CLS < 0.05.

2027 Cost, Security & Latency Pitfalls

Security: Never trust client-sent product prices in checkout actions; always query authoritative price_cents from DB by productId.
Cost (FinOps): Cache AI-generated product descriptions in DB columns once at publish time rather than calling an LLM on storefront page views.
SEO / CLS: Always specify width/height or fill aspect-ratio on product images so hero banners never shift layout.