Loading…
← HandbookLive
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 pageThe 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.
Architecture
How it’s wired
The full order→inventory loop is documented as a sequence diagram on the handbook home. JarvisOS is ghosted: a separate, isolated project reached only over signed webhooks.
2
signed webhooks (loop)
5 min
replay-guard window
≤60s
stock sync lag (ISR)
11
tables
Stack
Next.js 14 (App Router)TypeScriptSupabaseAnthropic ClaudeCloudinaryPayFastResendPostHogSentryZustandmaplibre-gl (Pargo/PUDO map)
AI
An Anthropic Claude chatbot — Haiku for tips and classifications, Sonnet for full consultations — with ephemeral prompt caching on the static system prompt.
Data model
11 tables
- products (variants, combos, live stock_count)
- orders / qr_cards / angels (loyalty)
- journal_entries (private AI hair journal) + journal_posts (public CMS)
- production_log (batch tracking)
Key decisions
Why it’s built this way
ADR-01
The engine is authoritative for inventory
- Context
- Two systems holding stock risks overselling.
- Decision
- A closed loop of two HMAC-signed webhooks; the store writes stock only via /api/stock-sync.
- Consequence
- Truthful live stock with a single source of truth.
ADR-02
Two distinct webhook auth schemes
- Context
- Outbound and inbound calls have different trust models.
- Decision
- Store→Engine uses Bearer + HMAC-SHA256(body); Engine→Store signs over timestamp.body with a 5-minute replay guard.
- Consequence
- Tamper- and replay-resistant in both directions.
ADR-03
Best-effort, non-blocking, no-op without secrets
- Context
- Checkout must never break if the integration is half-wired.
- Decision
- Both webhooks silently no-op when env vars are unset; idempotency lives on the engine keyed by payfast_payment_id.
- Consequence
- Safe to deploy partially configured.
The hard parts, solved
The bidirectional signed inventory loop
Two webhooks with mismatched auth schemes, a replay guard, and graceful degradation — documented end-to-end on the /docs home page as the flagship integration flow.
Streaming AI over a static, cached prompt
The chatbot streams via a ReadableStream with the ≥4096-token system prompt marked ephemeral for cache hits.
Sourced from sanyubotanicals — SUPPLY_CHAIN, constants/products.ts, repo code.
.jpg&w=3840&q=75)