Loading…
Sanyu Botanicals
An editorial e-commerce storefront for botanical hair care, with an AI hair chatbot, an "Angel" loyalty portal, and a live two-way inventory sync to the private engine.
View the product page- Data model
- 25 tables · 53 migrations · 8 stored RPCs
- Stack
- 12 technologies
- Provenance
- real build journals
The problem
Sell physical botanicals direct-to-consumer in ZAR with trustworthy local fulfilment, while keeping stock counts truthful against a single source-of-truth ops system, so the storefront never oversells.
.jpg&w=3840&q=75)
Architecture
How it’s wired
A container-level view of the real system, the boundaries, the trust edges, and where intelligence and money actually flow.
The full order→inventory loop is documented as a sequence diagram on the handbook home. The manufacturing engine is ghosted: a separate, isolated system reached only over two signed webhooks (two different shared secrets, a 5-minute replay guard), so the store mirrors stock but can never author it.
.jpg&w=3840&q=75)
By the numbers
25
tables · 53 migrations
8
stored RPCs
2
signed webhooks (the loop)
≤60s
stock sync lag (ISR)
Stack
Next.js 14 (App Router)TypeScriptSupabase (Postgres + RLS)Anthropic Claude Haiku 4.5CloudinaryPayFast (MD5 ITN)Vercel KV / Upstash (rate limit)ResendPostHogSentry v10Zustandmaplibre-gl (Pargo/PUDO map)
Intelligence
One fast model, Claude Haiku 4.5, runs the whole hair-care brain: a streaming conversational coach over a cached, ≥4096-token botanical knowledge base (marked ephemeral for cache hits), plus journal-history-aware daily tips and monthly reflections. Every call has a graceful fallback, so a mid-stream model hiccup surfaces as "Sanyu lost her thread," never a broken response.
Data model
25 tables · 53 migrations · 8 stored RPCs
- products, stock_count (engine-synced) + reserved_count, is_combo + combo_items JSONB, variant_group, soft-delete via deleted_at
- orders, status CHECK (pending|paid|packed|shipped|delivered|refunded|cancelled|expired), payment_method, a synced_at column with a partial index WHERE synced_at IS NULL for the backfill scan
- angel_points_ledger, append-only: every movement stores delta + balance_after, RLS scoped to the owning Angel
- reserve_stock / commit_stock / release_stock + recompute_combo_stock, inventory logic lives in the database, not app code
Key decisions
Why it’s built this way
Architecture Decision Records, the trade-offs made deliberately, in the open.
ADR-01
The engine owns inventory truth; the store only mirrors it
- Context
- Two systems holding stock risks overselling.
- Decision
- The storefront cannot write its own stock_count except through the signed /api/stock-sync, and the two webhook directions use two different shared secrets (store→engine vs engine→store), each with a 5-minute replay guard.
- Consequence
- Truthful live stock from a single source of truth, tamper- and replay-resistant both ways.
ADR-02
Rail-aware reservation expiry
- Context
- Card and EFT payments settle on very different timelines.
- Decision
- A release-reservations cron holds a PayFast reservation for 30 minutes but an EFT reservation for 3 business days (weekend-skipping business-day math); an expired hold releases the stock, and a late payment can still win the compare-and-swap.
- Consequence
- Stock isn’t locked forever by an abandoned cart, yet a slow EFT customer isn’t robbed of their jar.
ADR-03
Virtual "Angel" cards replace printed QR cards
- Context
- Printing and posting loyalty cards is slow and costly.
- Decision
- Each paid order mints a SANYU-<nanoid> code in the same qr_cards table and emails it, activating exactly like a printed card, idempotent on ITN retry and skipping buyers who are already Angels.
- Consequence
- Instant loyalty onboarding with no print run.
.jpg&w=3840&q=75)
The hard parts, solved
Where the engineering earned its keep
01
Oversell-proof stock, enforced in Postgres
reserve / commit / release are SECURITY DEFINER RPCs over available = stock_count − reserved_count. reserve_stock does SELECT … FOR UPDATE, then a conditional UPDATE … WHERE stock_count − reserved_count >= qty, a row-locked compare-and-swap, so two simultaneous checkouts can never both claim the last jar (a NULL stock_count means untracked / unlimited).
02
Combo stock as a trigger-derived cache
A combo’s stock_count = MIN over its components of floor(component.stock_count / qty_per_combo), recomputed by an AFTER UPDATE trigger with a recursion guard. Base products stay the single source of truth, so a bundle can never show "in stock" while one of its components is sold out.
03
Concurrency- and retry-safe PayFast fulfilment
The ITN handler rejects any mismatched amount, bails early if the order is already paid, and flips to paid with a compare-and-swap UPDATE … .neq("status","paid") so a duplicate ITN returns already_processed instead of double-fulfilling. Side-effects run only after the guarded flip.
Sourced from sanyubotanicals, SUPPLY_CHAIN, supabase/migrations (25 tables), lib/inventory/stock.ts, app/api/payfast/notify, lib/shipping.ts.
.jpg&w=3840&q=75)
Keep exploring