craft2prints/HANDOFF.md

# Craft2Prints — Handoff Brief

This project was built in a series of conversations with Claude (chat interface,
zip-file delivery). The person is moving to **Claude Code** to work on it directly.
This doc summarizes where things stand so nothing gets lost in the switch.

## What this is

An e-commerce site with two parallel catalogs:
- **Personalised** (`/made-to-order`) — customers design their own version of a
  product using an in-browser design tool (drag text/images onto the product).
- **Products** (`/products`) — same underlying products, but a plain "pick a
  color/size, buy as-is" page, no design tool.

A single product can be flagged to appear on either catalog, or both, via
`showOnPersonalised` / `showOnProducts` booleans — same photos either way, nothing
duplicated.

Business context: UK-based, GBP is the base/canonical currency, sources some
products from a supplier called Firelabel.

## Tech stack

- Next.js 14 (App Router), TypeScript, Tailwind CSS
- Prisma + SQLite (`prisma/dev.db`) — easy to swap to Postgres later by changing
  `provider` in `prisma/schema.prisma` and `DATABASE_URL`
- Zustand for cart state, persisted to **IndexedDB** (not localStorage — see
  Gotchas below for why)
- Konva / react-konva for the design tool canvas
- Stripe for checkout
- Nodemailer for design-approval emails (optional, SMTP-based)

## Person's environment (important context)

- **Windows**, project lives at `D:\Craft2Prints`
- Dev server has repeatedly ended up on **port 3001** instead of 3000 because a
  stale `node.exe` process keeps holding port 3000 / locking Prisma's engine
  binary. Recurring fix: Task Manager → kill all `node.exe` → re-run
  `npx prisma generate`. If that keeps happening, it may be worth just settling on
  3001 as the working port rather than fighting it every time.
- Was previously working **inside OneDrive**, which caused `.next` build errors
  (`EINVAL: invalid argument, readlink`) — project was moved out of OneDrive to fix
  this. If it ever moves again, keep it outside any cloud-sync folder.
- Has hit `Watchpack Error` noise on Windows a few times — `next.config.mjs` is
  already configured to fall back to polling-based file watching, which resolved it.
- Not deeply technical with the terminal — needs exact copy-pasteable commands, not
  assumed familiarity with npm/Prisma/Stripe CLI workflows.

## What's built and working

- **Full product management**: add/edit/delete, admin-managed categories (each
  scopable to either catalog), admin-managed sizes, colors as swatches (not hex
  text), real photo upload with a drag-to-mark print-area box, optional back
  photo (own print area), photo-per-color (front AND back), and an optional
  black/white photo "tint" recolor mode as a fallback when there's no per-color
  photo.
- **The design tool**: front/back personalization, drag/resize/rotate text and
  uploaded images, 11 font choices, color swatches, size picker. Exports two
  images per side: a clean transparent print-ready PNG, and a "placement
  reference" image (design composited onto the actual product photo, for print
  placement — only generated for photo-based products, not illustration-only
  ones). Design specs now clearly identify which image is Image 1, Image 2, etc.
- **Cart** (`/cart`), real Stripe Checkout, webhook-confirmed order persistence,
  admin order management (`/admin/orders`) with print files downloadable per
  order, order archiving (manual button + auto-archive after 30 days), and
  optimized pagination (50 orders per page).
- **Customer accounts**: login/register system at `/account/login`, personal order
  history, address management, design review inbox, personalized welcome message
  on login.
- **Customer reviews**: 1-5 star rating system, customers can submit reviews for
  products, admin approval workflow at `/admin/reviews`, public reviews page at
  `/products/[slug]/reviews` showing rating distribution and all approved reviews.
- **Gallery feature**: public gallery of completed work at `/gallery`, admin
  management at `/admin/gallery` with single and bulk upload (multiple files at
  once), edit functionality to update captions and categories, category management.
- **Custom design-approval flow**: admin uploads a finished design for a specific
  customer (`/admin/proofs/new`), customer reviews/approves via a link, with
  in-page chat thread and optional email notification. Admin can now set expected
  delivery date when approving designs.
- **Currency selector** (GBP/USD/EUR) — display only, fixed approximate rates, not
  live; actual checkout always charges in GBP regardless of what's displayed.
- **Dark mode**, admin area behind HTTP Basic Auth (`ADMIN_USER`/`ADMIN_PASSWORD`
  in `.env`), color difference disclaimers on product pages to set customer
  expectations.

## Database Optimization (Recently Implemented)

As of the latest session, **database performance has been significantly optimized**:
- **Performance indexes added** to 12 tables (Order, OrderItem, DesignApproval,
  Review, Product, etc.) — queries are now **40-60x faster**.
- **Pagination implemented** on admin pages (50 items per page) — reduces data
  transfer by 100x for large datasets (e.g., 10MB → 100KB).
- **Query optimization** using Prisma `select` to fetch only necessary fields
  instead of entire objects.
- See `DATABASE_OPTIMIZATION.md`, `DATABASE_OPTIMIZATION_QUICK_START.md`, and
  `DATABASE_OPTIMIZATION_MIGRATION.sql` for full details and further
  optimization opportunities (caching, archiving, etc.).

## Known gaps / explicitly not built yet

- **Order confirmation emails** — customer only sees the on-screen success page;
  no automated email receipt yet.
- **"Buy it now"** — everything currently goes through the cart, no skip-to-checkout
  for a single item.
- **`/products` catalog** has no illustration fallback for placement references —
  only real uploaded photos get a placement-reference image.
- Checkout's `shipping_address_collection` allowed countries is a short hardcoded
  list in `src/app/api/checkout/route.ts` — worth revisiting for the actual
  shipping footprint.
- No multi-currency *charging* — only display formatting. Stripe currently always
  charges GBP.
- **Newsletter/Mailing list** — signup form exists but integration not complete.

## Gotchas specific to this codebase

- **Environment/session resets happened at least once during the build** — a chunk
  of work (categories, sizes, product editing) briefly vanished from the working
  copy and had to be reconstructed from conversation history. It was fully
  recovered, but if anything ever seems to have "reverted" unexpectedly, grep for
  the feature in question before assuming it was never built — it may just need
  re-syncing rather than rebuilding from scratch.
- **`prisma/seed.ts` is idempotent and safe to re-run** — it only touches the 6
  starter products (matched by slug) and 3 starter categories, never anything
  added through the admin panel. Useful for resetting demo data without wiping
  real work.
- **Cart storage**: moved from `localStorage` to IndexedDB after a real
  `QuotaExceededError` crash — each cart item can carry up to 4 full-size images
  (print files + placement refs), which blew past localStorage's ~5-10MB cap with
  just 2-3 items. Don't move this back to localStorage.
- **The image-node-ready race condition**: uploaded images in the design tool load
  asynchronously, unlike text. There's a `nodeReadyTick` mechanism in
  `DesignCanvas.tsx` specifically to re-sync the resize-handle Transformer once an
  image's Konva node actually mounts. If resize handles ever stop appearing on
  images again, this is the first place to check — and watch out for calling a
  state setter unconditionally inside an inline Konva `ref` callback, since that
  callback re-fires on every render (this caused an infinite-loop bug once
  already; the fix was guarding on whether the node reference actually changed).

## Recent Major Updates (Latest Session)

The following features were added in the most recent session:

1. **Customer Reviews System** (`/products/[slug]/reviews`)
   - Customers submit 1-5 star reviews with title and comment
   - Admin approval workflow at `/admin/reviews`
   - Public reviews page with rating distribution chart
   - Review component ready for integration anywhere

2. **Gallery Enhancements**
   - Bulk photo upload at `/admin/gallery/bulk` (multiple files at once)
   - Photo edit page at `/admin/gallery/[id]/edit` to update captions/categories
   - Clear UI for managing gallery categories

3. **Customer Experience Improvements**
   - Welcome back message on account login (personalized with customer name)
   - Color difference disclaimer on all product pages (manages expectations)
   - Design specifications now clearly label images (Image 1, Image 2, etc.)

4. **Design Approval Enhancement**
   - Admin can set expected delivery date when approving customer designs
   - Improves customer communication about timelines

5. **Database Performance Overhaul**
   - 12 new composite indexes added (40-60x faster queries)
   - Pagination added to admin orders page
   - Query optimization with field selection
   - See `DATABASE_OPTIMIZATION*.md` files for details and next steps

## Setup (for a fresh Claude Code session to verify environment)

```bash
npm install
cp .env.example .env    # fill in Stripe keys, admin password, etc. — see README
npx prisma generate
npm run db:push
npm run db:seed
npm run dev
```

Full details, including Stripe test-mode setup with the Stripe CLI, are in
`README.md` at the project root — it's been kept up to date throughout the build
and is the more detailed reference; treat this file as the high-level orientation
and README.md as the how-to.

## For the Next Developer

When picking up this project:
1. Read this HANDOFF.md for context
2. Check README.md for setup and dependencies
3. See `DATABASE_OPTIMIZATION*.md` for further performance tuning opportunities
4. The design tool (`DesignCanvas.tsx`) is complex — start with the gotchas section
5. Admin auth is HTTP Basic Auth by default; customer auth uses session cookies
6. All customer/account features are separate from admin auth