Pak Jabit: full stack — storefront, Spree customisations, catalogue tooling

A South African men's apparel store on Spree 5.6 + Next.js 15. 160 products
live, three markets, live Malaysian courier rates, customer-owned carts.

What is here:
  storefront/  the Next.js app
  backend/     ONLY the custom Spree code. Spree itself is a prebuilt image
               that mounts no app code, so every file here needs an explicit
               volume entry in docker-compose.yml or it is silently ignored.
  catalogue/   the scripts that loaded and maintain the products
  docs/        manifest, mock registry, napkins

Real .env files are committed deliberately. This lives on the house's private
Gitea, and a clone that runs beats a clone that needs a secrets handover.
LANDMINE.md maps every key, what it opens, and what must be rotated before this
repo goes anywhere less private.

The admin API key used to be a literal in six catalogue scripts. They now read
SPREE_ADMIN_KEY from the environment and refuse to run without it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/napkin-payment-courier.md

@@ -0,0 +1,109 @@
+# 💳 Payment & Courier — Napkin Notes
+
+## Payment Gateways (SA Market)
+
+### Recommended Stack
+| Gateway | What it covers | Fees | Priority |
+|---------|---------------|------|----------|
+| **Payfast** | Cards (Visa/MC), EFT, SnapScan, Masterpass | 3.5% + R2/tx | Must-have |
+| **Payflex** | Buy now pay later (4 instalments) | They pay you upfront | High — big conversion booster for fashion |
+| **Yoco** | Cards, tap-to-pay (if physical retail later) | 2.6-2.95%/tx | Nice-to-have |
+
+### Why this stack
+- Payfast alone covers ~90% of SA payment methods
+- Payflex is the killer feature for apparel — "R1,500 jacket? Pay R375 × 4" removes price friction
+- Cards (Visa/MC/Amex) come free with Payfast
+- EFT = still king in SA, people trust bank transfers
+
+### NOT needed (yet)
+- Stripe — limited SA support, overkill for local-first
+- PayPal — high fees, withdrawal pain in SA
+- Crypto — niche, not the market
+
+### Integration notes
+- Spree has payment provider plugin architecture — write adapter, plug in API keys
+- Morne's company (NSH/INET) registers as merchant — they get the API keys
+- We build the pipe, they plug in credentials
+- Payfast has well-documented REST API + existing Spree community plugins
+
+---
+
+## Courier / Logistics (SA Market)
+
+### Recommended: Bob Go (aggregator)
+- **One API** → connects to 10+ SA couriers
+- API docs: https://api-docs.bob.co.za/bobgo
+- Couriers included: The Courier Guy, Pargo, RAM, SkyNet, Internet Express, DPD/Dawn Wing
+- Features: compare rates, print waybills, track parcels
+- Shopify integration exists → Spree adapter needed
+
+### What Bob Go solves (all 3 spec blockers)
+| Spec Action Item | Status |
+|-----------------|--------|
+| 🔴 Identify suitable SA courier/API | ✅ Bob Go = one API, all couriers |
+| 🔴 Confirm automated shipment creation | ✅ Bob Go API supports it |
+| 🔴 Confirm waybill generation | ✅ Bob Go handles waybills |
+
+### Direct courier alternatives (if Bob Go doesn't fit)
+- **The Courier Guy** — most popular SA e-commerce courier
+- **Internet Express** — free API integration
+- **CourierIT** — volume discounts
+- **Evership** — another aggregator (Fastway, RAM, Aramex, TCG, DPD)
+
+### Shipping zones consideration
+- SA is big — courier coverage varies by province
+- Major metros (Joburg, Cape Town, Durban) = next day
+- Rural = 3-5 days, some couriers don't cover
+- Bob Go handles zone logic per courier
+
+---
+
+## 🏷️ Mock Convention
+
+All test/sandbox values tagged with `#mock` in code and config.
+When going live: `rg '#mock'` → find all → replace with production credentials.
+
+```
+# Example in config:
+PAYFAST_MERCHANT_ID=10000100  #mock
+PAYFAST_MERCHANT_KEY=46f0cd694581a      #mock
+PAYFAST_PASSPHRASE=jt7NOE43FZPn        #mock
+PAYFAST_MODE=sandbox                     #mock → change to "live"
+BOBGO_API_KEY=test_xxxxxxxxxxxx          #mock
+PAYFLEX_API_KEY=staging_xxxxx            #mock
+```
+
+---
+
+## Open Questions
+- [ ] Local SA only or international shipping?
+- [ ] Currency: ZAR only or multi-currency?
+- [ ] Who registers as merchant — NSH or a new entity?
+- [ ] Cash on delivery — needed? (Still popular outside metros)
+- [ ] Payflex merchant approval — timeline?
+
+---
+
+## Architecture Summary
+
+```
+Buyer → Spree Storefront (Next.js)
+         ↓
+       Checkout
+         ↓
+    ┌────┴────┐
+    │ Payfast │ → Cards, EFT, SnapScan
+    │ Payflex │ → Buy now pay later
+    └────┬────┘
+         ↓
+    Order Created
+         ↓
+    Bob Go API → auto-select cheapest courier
+         ↓
+    ┌────┴────┐
+    │ Waybill │ → PDF generated
+    │ Tracking│ → number assigned
+    └────┬────┘
+         ↓
+    Customer gets tracking link
+```