Initial commit: Craft2Prints with Stages 1-3
This commit is contained in:
Andymick
+127
@@ -0,0 +1,127 @@
|
||||
# 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).
|
||||
- Cart (`/cart`), real Stripe Checkout, webhook-confirmed order persistence,
|
||||
admin order management (`/admin/orders`) with print files downloadable per
|
||||
order, and order archiving (manual button + auto-archive after 30 days).
|
||||
- Custom design-approval flow for one-off jobs: admin uploads a finished design
|
||||
for a specific customer (`/admin/proofs/new`), customer reviews/approves via a
|
||||
link, with an in-page chat thread and optional email notification.
|
||||
- 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`).
|
||||
|
||||
## 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.
|
||||
|
||||
## 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).
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user