How to Build an E-Commerce Store

<context>
App: E-Commerce Store
Difficulty: Intermediate
Estimated build time: 1–2 weeks

Data model:
  Product: id, name, slug, description, price, compare_at_price, images[], inventory_count, category_id, published
  ProductVariant: id, product_id, sku, size, color, price, inventory_count
  Order: id, customer_email, status (pending/paid/shipped/delivered/refunded), subtotal, shipping, tax, total, stripe_payment_intent, created_at
  OrderItem: id, order_id, product_id, variant_id, quantity, unit_price
  Cart: session_id (cookie), items[] — stored in a cookie or localStorage, not DB

Recommended build order:
  1. Product catalogue — Build a product listing page with image, name, price, and an "Add to Cart" button. Use Next.js SSG for product pages — fast loads and good SEO. Fetch product data from Supabase at build time.
  2. Shopping cart — Store the cart as a JSON array in a cookie or localStorage: [{productId, variantId, quantity}]. Add a cart sidebar that slides in on add. Show item count in the header. Persist across page navigations.
  3. Stripe Checkout — On checkout click, POST the cart to /api/checkout. Create a Stripe Checkout Session with line items mapped from your cart. Redirect the user to the Stripe-hosted checkout page. Handle success and cancel redirects.
  4. Webhook for order confirmation — Create a /api/stripe/webhook route. Verify the Stripe signature. On checkout.session.completed: create an Order row in your DB, decrement inventory, send a confirmation email via Resend.
  5. Order history for customers — Add a /orders page that shows a customer's order history when they enter their email. Look up orders by email (no account required for small stores). Show order status, items, and total.
  6. Admin panel — Build a simple /admin route (protected by a secret cookie or Clerk). Show all orders with status. Add buttons to update order status (shipped, delivered). Show low-inventory alerts.
  7. Search and filtering — Add a search input that filters products by name on the listing page. Add category filters and a price range slider. For large catalogues, move to server-side search with Supabase full-text search or Algolia.

Known pitfalls to avoid:
  - Fulfilling orders without verifying payment — never trust the success redirect URL to confirm payment. Only fulfil orders after receiving the checkout.session.completed webhook from Stripe.
  - Not handling inventory concurrency — two users might buy the last item simultaneously. Use a database transaction with a check: UPDATE products SET inventory = inventory - 1 WHERE inventory > 0 AND id = ?. Check the row count to confirm it succeeded.
  - Storing prices in the frontend cart — always recalculate prices server-side before creating the Stripe session. A user can modify their localStorage cart to change prices.

Tech stack (intermediate): Next.js + Stripe + Supabase + Cloudinary (images) — custom store, free at small scale
</context>

<role>
You are a Senior Full-Stack Engineer and product architect who has shipped production E-Commerce Stores before. You know exactly where developers get stuck and how to structure the project to avoid rewrites.
</role>

<task id="step-1-clarify">
Before writing any code or spec, ask me 3–5 clarifying questions that will meaningfully change the architecture. Focus on: scale expectations, auth requirements, platform (web / mobile / both), must-have vs nice-to-have features for the MVP, and any hard constraints (budget, deadline, existing infrastructure).

<example>
BAD: "What tech stack do you want to use?" — too broad, doesn't change architecture decisions.
GOOD: "Do you need real-time sync across devices, or is single-device with periodic refresh acceptable? This decides whether we use WebSockets or simple REST polling and significantly affects infrastructure complexity."
</example>
</task>

<task id="step-2-architect">
After I answer your questions, generate a complete project specification including:

1. Final tech stack with version numbers
2. Full file and folder structure
3. Complete database schema — every table, column, type, index, and foreign key
4. All API routes with request/response shapes and auth requirements
5. Component tree with TypeScript props interfaces
6. Auth and authorisation flow (who can do what)
7. Step-by-step implementation plan in the exact build order from <context> above
8. All environment variables with descriptions

<self_check>
Before presenting the spec, verify:
□ Every answer I gave in step 1 is reflected in the spec
□ The database schema matches the data model in <context>
□ The implementation plan follows the build order from <context>
□ No circular dependencies in the component tree
□ Auth is wired up before any protected routes are built
□ All known pitfalls from <context> are addressed in the spec
</self_check>
</task>

<task id="step-2.5-agents-md">
Generate an AGENTS.md file at the project root. This file is read automatically by Claude Code, Cursor, Windsurf, Sourcegraph Cody, and all major AI coding tools at the start of every session.

Include:
- Project overview (2–3 sentences)
- Tech stack with version numbers
- Folder structure with one-line descriptions
- Key architectural decisions and why they were made
- Coding conventions: naming (camelCase components, kebab-case files), max 200 lines per file, one concern per file
- Available commands: dev, build, test, lint, db:migrate, db:seed

Note in the file: "Cursor users can symlink .cursorrules → AGENTS.md. Claude Code users can symlink CLAUDE.md → AGENTS.md."
</task>

<task id="step-3-implement">
Implement the full project following the spec from step 2, in the exact order defined. For each step:
- Write the complete code (no placeholders or TODOs)
- Confirm the step is working before moving to the next
- Note any deviations from the spec with an explanation

<constraints>
- Max 200 lines per file. WHY: every file must fit in one AI context window for easy review and editing.
- One concern per file. WHY: mixing auth logic into API routes makes it impossible to reuse — extract to lib/auth.ts.
- TypeScript strict mode, no `any` types. WHY: catches data shape mismatches at compile time, not in production at 2am.
- All database queries in server components or API routes only. WHY: keeps credentials server-side, prevents accidental client-side exposure.
- All environment variables documented in .env.example. WHY: the next developer (or your future self) should be able to set up the project in under 5 minutes.
- Comment every non-obvious decision. WHY: AI tools read your comments to understand intent — without them, the next edit will break the pattern you established.
</constraints>
</task>