Platform Architecture
Two products. One backend (api.zerrar.com). Zerrar is a multi-channel commerce OS for Nigerian merchants — WhatsApp is one channel among many. The marketplace (zerrar.com) is the discovery layer where customers find and buy from verified vendors.
🛠️ Merchant App — Flutter (app.zerrar.com)
🚀
Onboarding & Login
Splash, 3 slides, login, biometric, PIN, free trial
4 screens
📊
Dashboard
Balance, plan, revenue forecast, reorder alert, best day, quick actions
1 + widgets
📦
Orders
All channels. Confirm → ship → deliver. COD + Paystack/Monnify/Flutterwave
3 screens
🛍️
Products & Variants
2-step add, cost price, discount price, dead stock filter, boost to Ads
4 screens
👥
Customers
LTV tiers (New/Regular/VIP/Whale), loyalty, broadcast trigger
2 screens
📣
Ads & Campaigns
Broadcasts (free-form) + Discovery Spark/Blaze/Inferno. Wallet validation.
3 screens
💰
Wallet
Available vs pending, fee transparency, 3 gateways, withdraw
3 screens
📈
Profitability
Margin table, 5 intelligence features, boost CTA, /products/profitability endpoint
2 screens
🧾
Expenses
Categories, recurring, receipt photo, feeds P&L
2 screens
📋
Tax & Compliance
VAT 7.5%, CAC/TIN from profile, tax filing → accounting@zerrar.com
2 screens
🖥️
POS
Walk-in, offline 24h cache, Cashier role-gated, receipt via WhatsApp/Bluetooth
3 screens
🚚
Delivery
Fez primary, Sendbox fallback, parallel quotes, 20% buffer, webhook tracking
2 screens
👤
Team
Owner/Admin/Staff/Cashier — role-gates entire app experience
2 screens
⚙️
Settings
Store, Paystack/Monnify/Flutterwave, chargeFeeTo, domain, plan, security, API
5 screens
🛒 Zerrar Marketplace — Next.js (zerrar.com)
🏠
Market Home
Hero, search, category grid, trending products, featured vendors, Discovery ads
1 screen
🏪
Vendor Profile
zerrar.com/vendors/[slug] — products, about, verified badge, reviews
1 screen + tabs
📱
Product Detail
zerrar.com/vendors/[slug]/[productId] — gallery, variants, Add to Cart, WhatsApp vendor
1 screen
🛒
Cart Drawer
Multi-vendor cart (zerrar_cart_v1 localStorage). Items grouped by merchant.
1 drawer
💳
Checkout (3 steps)
Address → Shipping rates (Fez+Sendbox) → Paystack payment OR COD
3 steps
✅
Order Success
Paystack verify + COD confirm. Order ref, WhatsApp vendor link.
2 variants
📍
Order Tracking
Timeline: placed → confirmed → shipped → out for delivery → delivered
1 screen
Brand Design System
Sourced from ThemeContext.tsx and Logo.tsx. Applies to both merchant app (Flutter) and marketplace (Next.js). The rule is absolute: NO GREEN. Gold is the positive/success/active colour.
Navy Palette (ThemeContext.tsx)
#0B1520
Deep (bgPage)
Deep (bgPage)
#162032
Mid (bgCard)
Mid (bgCard)
#1C2940
Raised
Raised
#1E3048
Border
Border
#A8B8CC
Muted
Muted
#7A90A8
Label
Label
Gold Palette (ThemeContext.tsx)
#B87A10
Dark
Dark
#C98A1A
Mid ★
Mid ★
#D4981E
Bright
Bright
#F0C040
Light
Light
Surface (Light Mode)
#F8F6F2
bgPage
bgPage
#FFFFFF
bgCard
bgCard
#F0EDE8
bgRaised
bgRaised
#E2D9CC
border
border
Status — NO GREEN
- Success/Active/Confirmed/Paid/Verified → brandSurface (gold bg) + brandSurfaceText (#C98A1A). NEVER green.
- Error → errorBg / errorText #F87171
- Warning → warningBg / warningText #D97706
- Banned codes: #34D399 #6EE7B7 #10B981 #059669 #064E3B — all replaced with gold tokens
- Green only: WhatsApp brand icon/button where Meta requires it
Typography Scale (Both Products)
- Display: Playfair Display — headings, hero, splash
- Body: DM Sans 22/15/14/13/12/11/10px scale
- Amounts: JetBrains Mono — every ₦ figure, no exceptions
- Primary button on gold bg: #0B1520 hardcoded (not a token)
Subscription Plans
- Free: 30-day strict trial. Paywall on day 30. Cron warnings: day 7/14/23/27/28/30
- Starter: ₦8,000/mo
- Pro: ₦15,000/mo
- Growth: ₦25,000/mo
- Enterprise: custom pricing, custom limits table, never expires
- Expired plan → TRIAL_EXPIRED 403 on all API calls
Revenue Model
- 5% commission — deducted silently from merchant settlement. Never shown to buyers or sellers on marketplace UI.
- Discovery Ads: Zerrar takes 10% of spend (Spark ₦10k / Blaze ₦15k / Inferno ₦30k)
- WhatsApp broadcast costs: Meta charges merchants directly — not Zerrar
- Paystack fee: 1.5% under ₦2,500; 1.5%+₦100 capped ₦2,000 above. chargeFeeTo controls who bears it.
Onboarding & Login
Multi-channel commerce OS positioning — not WhatsApp-native. 3 slides: every channel, business intelligence, ads. Free trial starts at step 1 (whatsappDone dropped, currentStep starts at 1).
Splash
2s auto-advance. Auth check → Dashboard or Login. Z-mark animation 400ms.
Z
Zerrar
Sell everywhere.
Manage one place.
Onboarding Slide 1/3
Swipeable. Skip top-right. Correct positioning: multi-channel commerce OS. Replace placeholder images before launch.
🛒
Multi-Channel Commerce OS
Sell on every channel.
Manage from one place.
Orders from your storefront, social media, WhatsApp, and walk-in customers — all in one dashboard.
Login
Email + password. Biometric on return. 5 failed = 30-min lockout. httpOnly session cookie. Google SSO.
Z
ZerrarWelcome back
Sign in to your store
Email Address
you@example.com
Password
••••••••👁
Forgot password?
or
G
🔑
No account? Create one free →
Dashboard / Home
Command centre. Plan badge in balance card. Revenue Forecast (useDashboardStats.ts). Reorder Alert (GET /products/low-stock). Best Day to Sell (client-side from order timestamps). FCM badge on bell.
Dashboard — Main Screen
Pull-to-refresh. Balance collapses on scroll. All intelligence widgets visible above the fold.
Good morning 👋
Adewale's Fashion Store
🔔
A
Wallet Balance
₦248,500
+₦12,400 today · 48h settlement
📦 12 Orders
⚡ 3 Pending
Pro · ₦15,000/mo
📈
On track for ₦320,000 this month
Daily avg ₦11,428 · 68% to target
⚠️
Agbada Set (L) — Reorder Now
2 left · avg 8/wk · 34% margin
Today's Stats
This week ›Revenue
₦64,200
↑ 18%
Orders
23
↑ 5 new
Net Profit
₦18,900
29.4% margin
Avg Order
₦2,791
↑ ₦310
Quick Actions
📦
New Order➕
Add Product💸
Withdraw📣
Broadcast🖥️
POS🚚
Delivery📈
Reports👥
CustomersRecent Orders
All ›👤
Amara Okafor
2 items · Storefront
₦4,500
New
👤
Tunde Bello
1 item · WhatsApp channel
₦12,000
Processing
👤
Chisom Eze
3 items · POS Walk-in
₦7,800
Delivered
🏠
Home
📦
Orders
🛍️
Products
💰
Wallet
☰
More
Orders Module
All channels in one list. PATCH /orders/:id/status. COD (no 48h hold) and Paystack (48h hold) flows differ. Source badge per card: Storefront / WhatsApp channel / POS / Social.
Orders List
FCM real-time push for new orders. Filter tabs. Source badge per card.
Orders
23 today · 3 pending · /orders?status=
All (23)
New (5)
Processing (3)
Delivered (14)
Cancelled (1)
#ORD-2847
Today 10:32
New
👤 Amara Okafor · +234 803 XXX
Ankara Fabric ×2 · Purse ×1
₦4,500
Storefront →
#ORD-2846
Today 9:15
Processing
👤 Tunde Bello · +234 806 XXX
Agbada Set — Size L ×1
₦12,000
WhatsApp →
#ORD-2845
Yesterday 4:48
Delivered
👤 Chisom Eze · +234 811 XXX
Lace ×2m · Thread ×1
₦7,800
Fez Delivery
🏠
Home
📦
Orders
🛍️
Products
💰
Wallet
☰
More
Order Detail (Bottom Sheet)
- Customer name, phone, full address
- Items: qty, variant, unit price, subtotal
- Payment: gateway (Paystack/Monnify/Flutterwave/COD) + status
- Delivery: courier + tracking link + ETA
- Timeline stepper: placed → confirmed → shipped → delivered
- Actions: Confirm / Mark Shipped / Delivered / Cancel
- Open in WhatsApp button → prefilled message to customer
COD vs Paystack Flow
- COD: order confirmed, delivery booked, merchant marks delivered, merchant collects cash — no Paystack lock
- Paystack: 48h hold after "delivered" confirmation, then wallet balance released
- COD bypass: zerrar.com/checkout/success COD page skips Paystack verification
- Cancelled + Paystack: auto-refund initiated
Products & Variants
2-step creation. costPrice field (Prisma Decimal? @default(0)) is critical for profitability. Discount price overrides selling price on marketplace everywhere. Dead Stock filter tab.
Product Grid
2 columns, uniform height:66 body. Discount price shows over selling price. Cost + margin shown for merchant context.
Products
48 active · 3 low stock · GET /products
🔍 Search products...
All
Active
Low Stock
Draft
Dead Stock
👗
Ankara Fabric
₦3,500
Cost ₦2,200 · 37%
Stock: 24
👘
Agbada Set
₦12,000
₦15,000
⚠ Stock: 2
👜
Leather Purse
₦8,500
Cost ₦5,000 · 41%
Stock: 11
🧵
Aso-Oke (2m)
₦5,200
⚠ Stock: 1
+
🏠
Home
📦
Orders
🛍️
Products
💰
Wallet
☰
More
Customers Module
Auto-created from orders across all channels. LTV tier system feeds broadcast segmentation. Loyalty: Bronze/Silver/Gold with 100pt welcome bonus.
Customer List
Sorted by LTV desc. Tier badges. Search by name or phone.
Customers
142 total · 18 new this month
🔍 Search by name or phone...
A
Amara Okafor
+234 803 456 7890
LTV: ₦87,400
34 orders
₦87,400
VIP
T
Tunde Bello
+234 806 234 5678
LTV: ₦22,000
8 orders
₦22,000
Regular
C
Chisom Eze
+234 811 123 4567
LTV: ₦4,500
1 order
₦4,500
New
Ads & Campaigns
Two types: Broadcasts (free-form, Meta charges merchant directly — NOT Zerrar) and Discovery Ads (Zerrar takes 10% of spend). Tiers: Spark ₦10k / Blaze ₦15k / Inferno ₦30k. Wallet validation inline.
Ads Overview
Discovery plan badge, live campaign metrics, wallet balance validation inline at budget step.
📣 Ads & Campaigns
Broadcasts — Meta charges you directly. Discovery Ads — Zerrar takes 10% of spend. Meta Pixel + Google Merchant on all plans.
3
Active
₦48k
Spent
1,240
Reached
Discovery Plan
Upgrade ›⚡ Blaze
Featured + Meta Ads · All analytics
₦15k/mo
Active Campaigns
+ NewAnkara Sale — June
Active
Discovery · ₦20,000 budget · ₦12,400 spent · Zerrar fee ₦2,000
840Reached
124Clicks
₦8,200Revenue
Broadcast #14 — Marketing
Sending
142 customers · Meta charges directly · Utility→Marketing flow
64Delivered
28Opened
12Replied
⚠️ Wallet balance ₦248,500 — sufficient for selected budget ₦20,000
Wallet & Payouts
Subscription model — no per-order commission shown. Paystack fee transparent per transaction. chargeFeeTo controls who bears gateway fees. All 3 gateways shown in transaction feed.
Wallet Screen
Available vs pending. Subscription plan label. Fee breakdown per transaction. JetBrains Mono for all amounts.
Available Balance
₦248,500.00
+ ₦32,000 pending (releases in 24–48h after delivery)
Plan: Pro ₦15,000/mo · Subscription model — no per-order commission
💸
Withdraw
🏦
Bank Details
Transactions
Export CSV ›🏆
Order #2847 — Storefront
Today 10:35 · Paystack · cust bears fee
+₦4,500
Fee ₦67
❌
Discovery Ad — Ankara Sale
Today 8:00 · 10% Zerrar fee
-₦2,000
🏆
Order #2840 — WhatsApp
Yesterday 3:12 · Monnify
+₦11,400
❌
Withdrawal → GTBank
Jun 5 9:00
-₦50,000
❌
Pro Plan Subscription
Jun 1 · Recurring Paystack
-₦15,000
Profitability Insights
Backend: GET /products/profitability (MUST be before /products/:id in controller). Shows warning if less than 20% of products have cost prices. 5 intelligence features built from real data.
Profitability Screen
KPI cards → cost-price warning → insights → margin table with Boost CTA (unitsSold > 0 only).
📈 Profitability
Gross Margin
34.2%
Net Profit (Jun)
₦84,200
COGS (Jun)
₦162,400
Dead Stock
4 items
⚠️ 28/48 products missing cost prices — profitability data incomplete. Add cost prices in Products.
💡 Revenue Forecast
On track for ₦320,000 this month
Daily avg ₦11,428 × 28 days = ₦320k. 68% to target.
View full forecast →
⚠️ Dead Stock Alert
4 products haven't sold in 60+ days
Lace Fabric Blue, Men's Cap Grey, Beaded Bracelet, Agbada XS.
Create campaign →
📅 Best Day to Sell
Fri & Sat are your peak days
72% of revenue Thu–Sat. Schedule broadcasts Wednesday evenings.
Schedule broadcast →
Product Margins
Sort: Margin ↓PRODUCTSOLDMARGIN
Leather Purse4241%
Ankara Fabric8737%
Boost
Agbada Set1212%
Aso-Oke3—No cost
Expenses Tracker
Deferred import (lazy load). Revenue − COGS − Expenses = Net Profit shown in header. Recurring expenses flagged. Receipt photo stored in cloud.
Expenses Screen
P&L summary bar (total expenses / revenue / net profit). Category filter. Recurring flag. FAB adds expense.
Expenses
June 2026 · 11 items
All
Overhead
Operations
Marketing
Staff
Total Expenses
₦48,200
Revenue
₦246,000
Net Profit
₦84,200
🏠
Shop Rent
Overhead
-₦15,000
Jun 1
↺ Monthly
📦
Packaging Materials
Operations
-₦4,800
Jun 3
⚡
Generator Fuel
Utilities
-₦3,200
Jun 5
📣
Instagram Ads
Marketing
-₦10,000
Jun 7
👤
Staff Salary — Funmi
Staff
-₦35,000
Jun 1
↺ Monthly
+
Tax & Compliance
VAT 7.5%. CAC/TIN/NIN pulled from merchant profile (submitted at onboarding — never ask to re-enter). Tax Filing Service: request TIN registration or VAT filing → emails fire to accounting@zerrar.com + hello@zerrar.com + merchant.
Tax Screen
Tabs: Overview / VAT / Company Reg / Filing Service. CSV export. Filing due alert.
Tax & Compliance
Financial year: Jan–Dec 2026
Overview
VAT
Company Reg
Filing Service
⚠️ VAT Filing Due: 21 July 2026 — export CSV and submit to FIRS
VAT Summary — June 2026
Due Jul 21
Total Sales (incl. VAT)₦246,000
VAT Collected (7.5%)₦17,209
Input VAT (Purchases)₦3,820
Net VAT Payable₦13,389
Company Registration
Verified
Business NameZerrar Tech. Ltd
RC NumberRC-XXXXXXX
TIN••••••••••
NIN (masked)••••••••••
POS Point of Sale
Walk-in sales. Must work offline — product list cached for 24h (critical for NEPA situations). Sales queued locally, synced on reconnect. Cashier role = POS only.
POS Screen
3-column grid. Offline badge when disconnected. Cart bar + checkout button. Cashier role-gated.
🖥️ POS
● OFFLINE · Cached
🔍 Search...
👗
Ankara Fabric
₦3,500
👘
Agbada Set
₦12,000
👜
Leather Purse
₦8,500
🧵
Aso-Oke
₦5,200
💍
Bead Necklace
₦2,800
🎒
School Bag
₦6,500
2 items in cart₦16,000
Proceed to Checkout →
Delivery Management
Fez Delivery primary. Sendbox fallback (only shown if Fez unavailable or quote > 15% higher). Parallel quote model, 20% buffer shown to customers. Webhook-based tracking updates.
Delivery Screen
Summary (active/delivered/costs). Active shipment cards per order with courier badge.
Delivery
8 active shipments
8
Active
24
Delivered
₦14,200
Costs
#ORD-2847 — Amara Okafor
In Transit
📍 14 Adeleke St, Surulere, Lagos
Courier:
Fez Delivery
ETA: Jun 8, 2–5 PM#ORD-2840 — Tunde Bello
Awaiting Pickup
📍 22 Eko Hotel Rd, VI
Courier:
Sendbox
Pickup: Today 3 PMTeam Management
4 roles gate the entire app. Cashier = POS only. Role badge colours must be consistent across all screens. Invite via email or phone.
Team Screen
Consistent role badges everywhere: gold=owner, blue=admin, amber=staff, purple=cashier.
Team
4 members · 1 invite pending
A
Adewale Benson
matthewadedeji@zerrar.com
Owner
F
Funmi Adeyemi
Store Manager
Admin
K
Kola Nwachukwu
Sales Staff
Staff
B
Bimpe Osei
POS only
Cashier
Settings & Profile
Store info, Paystack/Monnify/Flutterwave gateways, chargeFeeTo (merchant/customer), custom domain, plan badge with trial days, API & Webhooks, security. WebViews must have back button + loader.
Settings Screen
Profile header with plan badge. Grouped: Store / Payments / Notifications / Account.
A
Adewale's Fashion Store
adewale.zerrar.com
Pro · ₦15,000/mo · 14 days left
Store
🏪
Store Information›🌐
Custom Domainadewale.com›🎨
Storefront Theme›Payments
💳
Payment GatewaysPaystack ✓›💸
Charge Fees ToCustomer›🚚
Shipping Settings›Notifications
🔔
New Orders💰
Payment Received📦
Low Stock AlertsAccount
🔐
Security & PIN›📋
Subscription PlanPro ₦15k›📊
API & Webhooks›🚪
Sign OutMarketplace Home — zerrar.com
The discovery layer. SEO-optimized Next.js. Customers browse verified vendors by category, state, or trending products. Multi-vendor cart (zerrar_cart_v1 localStorage, max 50 items/99 per item). Commission deducted silently — never shown to buyers or vendors.
Market Home — Buyer View
Hero search → category grid → trending products → featured vendors (Discovery ad placement) → blog.
Z
Zerrar🔍🛒
Discover Nigerian
Vendors You Can Trust
Shop verified sellers across fashion, hair, beauty, kids, wellness & home.
🔍 Search products or vendors...
Fashion
Hair
Beauty
Jewels
Kids
Wellness
Home
Trending Products
View all ›👗
Ankara Fabric 6yds
Adewale's Fashion
₦3,500
👜
Leather Tote Bag
Lagos Leathers
₦8,500
₦10,000
Featured Vendors
Discovery Ads · Blaze tier🛍️
✓ Verified
Adewale's Fashion
Fashion · Lagos
48 products
💍
✓ Verified
Beads & Baubles
Jewels · Abuja
31 products
🏠
Home
🔍
Search
🛒
Cart
📦
Orders
👤
Account
Cart Behaviour (zerrar_cart_v1)
- React Context + localStorage, versioned zerrar_cart_v1
- Max 50 items total, 99 per item (abuse prevention)
- Client-side price sanitization, server-side price re-validation at checkout
- CartDrawer shows items grouped by merchant (multi-vendor)
- CartButton in navbar with item count badge
- Commission deducted silently — never shown to buyer
Search Page (zerrar.com/search)
- Auto-search after 2 characters, 400ms debounce
- Tabbed results: Products / Vendors / All
- Filter by category (7 categories) and state (36 states)
- LocalBusiness + Product JSON-LD schema on vendor + product pages
- GA4: G-4JJ7BEF13Y tracking on all pages
Discovery Ad Placements
- Spark ₦10k/mo — Basic placement in category pages
- Blaze ₦15k/mo — Featured Vendors section on home + category pages
- Inferno ₦30k/mo — Premium top placement + Google Ads + priority
- All tiers: Meta Pixel, Google Merchant, analytics, WhatsApp broadcasts
- Zerrar takes 10% of ad spend as platform fee
Vendor Profile zerrar.com/vendors/[slug]
Per-vendor page with LocalBusiness JSON-LD schema. Gold Verified Badge shown prominently — signals identity verification to buyers. Products tab, About tab. Internally routed via /vendors/slug (not external storefront links).
Vendor Profile Page
Hero with store logo, verified badge, stats. Product grid below. WhatsApp vendor button.
← zerrar.com
🛍️
Adewale's Fashion Store
Fashion · Lagos Island
✓ Verified
48
Products
142
Orders
4.8★
Rating
Products
About
Reviews
👗
Ankara Fabric
₦3,500
👜
Leather Purse
₦8,500
👘
Agbada Set
₦15,000
₦12,000
🧵
Aso-Oke 2m
₦5,200
Product Detail zerrar.com/vendors/[slug]/[productId]
Product JSON-LD schema. Image gallery. Variant selector. Add to Cart (multi-vendor cart). "Ask Vendor on WhatsApp" button. Discount price shown over selling price. Related products from same vendor below.
Product Detail Page
Image gallery top. Name, price (discount over selling), variants, Add to Cart, WhatsApp button.
👗
← Store
🛒 2
🏪 Adewale's Fashion Store ✓
Premium Ankara Fabric 6yds
₦3,500
High-quality Ankara fabric, 6 yards. Suitable for dresses, skirts, and traditional attire. Multiple patterns available.
Pattern
Blue Geo
Red Floral
Yellow
Length
6 yards
4 yards
Cart Drawer
Multi-vendor cart. Items grouped by merchant. Client-side price sanitization. Server-side re-validation at checkout. Max 50 items / 99 per item. Commission invisible to buyer.
Cart Drawer
Slides in from right. Items grouped by merchant. Qty adjust. Proceed to Checkout button.
Your Cart
3 items · 2 vendors🏪 Adewale's Fashion Store
👗
Ankara Fabric 6yds
Pattern: Blue Geo · 6yds
−
2
+
₦7,000
👜
Leather Tote Bag
Colour: Brown
−
1
+
₦8,500
🏪 Beads & Baubles
💍
Gold Beaded Necklace
Size: Medium
−
1
+
₦4,500
Checkout 3-Step Flow
Step 1: Delivery address (name, phone, address, state, LGA/area). Step 2: Shipping rates — POST /market/checkout/rates (Fez + Sendbox parallel, lowest + 20% buffer). Step 3: Payment — Paystack authorization URL OR COD. POST /market/checkout/create → Paystack redirect.
Step 1 — Delivery Address
No account required. Name, phone, address, state, LGA from ng_lgas_with_areas.ts constants. Form validation before proceeding.
Checkout
Step 1 of 31
Address
2
Delivery
3
Payment
Delivery Information
Order Summary (3 items)
Ankara Fabric ×2₦7,000
Leather Tote ×1₦8,500
Bead Necklace ×1₦4,500
Subtotal₦20,000
Step 2 — Shipping Rates
POST /market/checkout/rates. Fez + Sendbox in parallel. Lowest + 20% buffer. Per-merchant rate. Grand total shown.
Checkout
Step 2 of 3✓
Address
2
Delivery
3
Payment
Delivery to Surulere, Lagos
Fez Delivery (Lagos→Lagos)
1–2 business days
₦3,240
Sendbox Standard
1–3 business days
₦3,520
Rates include 20% buffer. Zerrar books cheapest available courier at dispatch.
Subtotal₦20,000
Delivery (Fez)₦3,240
Grand Total₦23,240
Step 3 — Payment Method
POST /market/checkout/create → Paystack authorization URL OR COD. COD = Pay on Delivery (merchant reviews, may require upfront).
Checkout
Step 3 of 3✓
Address
✓
Delivery
3
Payment
Choose Payment Method
Pay Now (Card / Transfer)
Instant payment via Paystack. Secured by buyer protection.
Pay on Delivery (COD)
Pay when your order arrives. Subject to vendor approval.
Items (3)₦20,000
Delivery₦3,240
Total to Pay₦23,240
Checkout Backend Flow (Real)
- POST /market/checkout/rates → Fez + Sendbox parallel → lowest + 20% buffer per merchant
- POST /market/checkout/create → creates MarketOrder in DB → Paystack initialize with split (95% merchant, 5% Zerrar) → returns auth URL
- Customer redirected to Paystack → pays → redirected to /checkout/success?reference=xxx
- GET /market/checkout/verify/:ref → verifies with Paystack → creates Order per merchant in DB → merchants notified
COD Flow
- COD selected → POST /market/checkout/create with paymentMethod: COD → order created without Paystack
- /checkout/success COD page bypasses Paystack verification entirely
- Merchant sees COD order in dashboard → must confirm
- Delivery booked → customer pays on arrival → merchant marks delivered → Zerrar commission deducted at settlement
- 3 missed COD settlements → account review triggered
Buyer Protection
- All prepaid orders covered by Zerrar Buyer Protection
- Item doesn't arrive or doesn't match description → Zerrar investigates → refund
- Dispute raised by buyer → merchant has 48h to respond
- Zerrar superadmin reviews dispute via dispute management tool
- Refund: Paystack reversal to original payment method
Order Success & COD Confirmation
Two variants: Paystack success (GET /market/checkout/verify/:ref) and COD confirm (no verification, order already created). Both show order reference, summary, and WhatsApp vendor link.
Paystack Success Page
GET /market/checkout/verify/:ref. Payment confirmed → gold check icon. Order ref, summary, WhatsApp vendor link.
Order Confirmed!
Payment successful. Your order has been placed with 2 vendors and they've been notified.
Order Ref: ZR-2847-AMARA
Items3 items
DeliveryFez · 1–2 days
Total Paid₦23,240
PaymentPaystack ✓
COD Confirmation Page
No Paystack verification. Warm amber banner reminding buyer they'll pay on delivery. Clear order details.
Order Placed — ZR-2848-TUNDE
Delivery addressSurulere, Lagos
Expected1–2 business days
Amount to pay₦23,240 (on delivery)
Order Tracking Timeline
Timeline-based order tracking. Status updates pushed via Fez/Sendbox webhook → backend → customer notified via their order channel. Gold dots for completed steps, animated dot for current step.
Order Tracking Screen
Timeline: placed → confirmed → shipped → out for delivery → delivered. Gold = completed. Amber dot = current.
ZR-2847-AMARA
Out for delivery · Fez Delivery
✓
Order Placed
Jun 7, 10:32 AM
Payment confirmed via Paystack
✓
Confirmed by Vendor
Jun 7, 11:15 AM
Adewale's Fashion confirmed your order
✓
Picked Up
Jun 7, 2:00 PM
Fez Delivery picked up from vendor
Out for Delivery
Jun 8, 9:00 AM
Your order is on its way · ETA 2–5 PM
Delivered
Estimated Jun 8
Full Specification Table
Every screen. Real codebase data. Required v1.0 · Important v1.1 · UX Fix known issue · Fix code bug · New not yet built
| Screen | Requirements | Code Notes / Issues | Tag |
|---|---|---|---|
| Splash | Auth token check. Route Dashboard or Login. Z-mark animation 400ms. | Token refresh silently here if expired. Dio 401 interceptor → refresh → retry. | Required |
| Onboarding | 3 slides: multi-channel OS / business intelligence / ads+discovery. Skip button. Progress dots. | Do NOT say "WhatsApp-native" — WhatsApp is one channel. Replace placeholder images before launch. | UX Fix |
| Login | Email + password. Biometric return. Google SSO. Forgot password → zerrar.com/reset. 5 attempts → 30-min lockout. httpOnly session cookie. | DM Sans 14px uniform on all form labels across all screens. currentStep starts at 1 (whatsappDone dropped from onboarding). | Required |
| Dashboard | Wallet balance + plan badge. Revenue Forecast (useDashboardStats.ts). Reorder Alert (GET /products/low-stock + margin). Best Day to Sell (client-side order timestamps). 8-item quick actions. Recent 5 orders with channel source. Stats: revenue/orders/net profit/AOV. | FCM badge on bell. Stats from GET /orders + GET /merchants/usage. All ₦ amounts: JetBrains Mono. | Required |
| Orders | All channels. Filter: All/New/Processing/Delivered/Cancelled. Source badge per card. FCM real-time. PATCH /orders/:id/status. COD vs Paystack flow differ. | FCM token must refresh on every foreground event and sync to backend immediately. | Required |
| Products | 2-column grid, uniform height:66 body. 5 filter tabs (All/Active/Low Stock/Draft/Dead Stock). Discount price over selling price. Cost price + margin shown. | Grid: 2 full columns on all screen widths. onInput handler REQUIRED alongside onChange on all TextFields (confirmed paste bug). | Fix |
| Add Product | Step 1: name/category/desc/selling/cost/discount/images/stock/SKU. Step 2: variants (max 3 option types, 100 combos). "Boost this product" CTA → /ads?boost=[id] (only if unitsSold > 0). | costPrice: Prisma schema field Decimal? @default(0). Route /products/profitability must appear BEFORE /products/:id in controller. | Fix |
| Customers | List sorted by LTV desc. Tier badges (New/Regular/VIP/Whale). Search. Profile: orders, spend, AOV, loyalty tier (Bronze/Silver/Gold, 100pt welcome), broadcast trigger, notes. | Auto location permission: do NOT request on launch — defer to feature trigger. LTV feeds broadcast audience segmentation. | UX Fix |
| Ads | Broadcasts (free-form, 3 categories: Utility/Marketing/Conversational, Meta charges merchant directly) + Discovery (Spark/Blaze/Inferno). Wallet validation inline at Step 4. openCreateWithProduct method on useBroadcasts for Boost flow. | Wallet balance must be checked inline at budget step — disable launch if balance < budget. Broadcast modal: full-height draggable sheet. | Required |
| Wallet | Available vs pending (48h release). Subscription plan label (no per-order commission). Paystack fee transparent per txn (chargeFeeTo). All 3 gateways (Paystack/Monnify/Flutterwave) in feed. CSV export. | JetBrains Mono for ALL monetary amounts everywhere in the app — no exceptions. | Required |
| Profitability | GET /products/profitability?from=&to=. KPI: gross margin, net profit, COGS, dead stock count. No-cost-price warning if <20% products have costPrice. 5 intelligence features. Margin table. Boost CTA (unitsSold > 0). | CRITICAL: route /products/profitability must be BEFORE /products/:id in products.controller.ts — otherwise intercepted as :id lookup. | Fix |
| Expenses | P&L summary (expenses/revenue/net profit). Category filter (Overhead/Operations/Staff/Marketing/Equipment/COGS/Other). Itemised list, recurring flag. Add form: name/amount/category/date/photo/recurring/notes. | Deferred import (lazy load). Net profit = revenue − COGS − expenses — stays in sync with Profitability page calculation. | Important |
| Tax | VAT 7.5% summary, filing due date alert, company reg tab (CAC/RC/TIN/NIN pulled from profile — do NOT re-ask). CSV export. Tax Filing Service: select TIN/VAT → emails accounting@zerrar.com + hello@zerrar.com + merchant. | Pull business name, CAC, address, phone, TIN from existing merchant profile. Only ask for NIN and desired service. | Important |
| POS | 3-column grid, search, offline cache 24h, cart, checkout (discount → payment → receipt via WhatsApp/Bluetooth/skip). Cashier role = POS only. Offline badge when disconnected. | Product list cached locally 24h. Sales queued, synced on reconnect. Critical for unreliable Nigerian network. | Required |
| Delivery | Summary (active/delivered/costs). Fez primary. Sendbox fallback (only if Fez unavailable or >15% higher). Parallel quote, 20% buffer. Waybill + tracking link sent to customer. Webhook status sync. | COD "Delivered" triggers separate payment collection flow. Failed pickup → retry notification to merchant. | Required |
| Team | 4 roles: Owner/Admin/Staff/Cashier. Consistent badge colours all screens: gold=owner, blue=admin, amber=staff, purple=cashier. Invite via email+phone. Pending invites with resend/cancel. | Role badge sizes and fonts pixel-identical across all screens — inconsistent per testing feedback. | UX Fix |
| Settings | Store info, custom domain, storefront theme. Paystack/Monnify/Flutterwave toggles. chargeFeeTo (merchant/customer). Shipping settings. Notification toggles. Plan + trial days. API & Webhooks. Security/PIN. Sign out. | WebView: any settings that open web links must have back button + loading indicator. | UX Fix |
| Market Home (zerrar.com) | Hero search, 7 category grid, trending products, featured vendors (Discovery ad placement), blog teaser. Multi-vendor cart (zerrar_cart_v1 localStorage). Commission invisible to buyer. | GA4: G-4JJ7BEF13Y on all pages. Sanity CMS blog (project xstg9hlt, useCdn: false). Next.js + Cloudflare Pages. | Required |
| Vendor Profile (zerrar.com/vendors/[slug]) | LocalBusiness JSON-LD schema. Gold Verified Badge. Product grid, About tab, Reviews tab. WhatsApp vendor button. Stats: products, orders, rating. Internal /vendors/slug paths (not external storefront links). | Route: internal zerrar.com/vendors/[slug] — NOT shop.zerrar.com (slug.zerrar.com = Cloudflare Worker storefront, separate product). | Required |
| Product Detail (zerrar.com/vendors/[slug]/[productId]) | Product JSON-LD schema. Image gallery. Variant selector. Add to Cart (multi-vendor). "Ask Vendor on WhatsApp" button. Discount price over selling price. Related products from same vendor. | Client-side price sanitization. Server-side price re-validation at checkout. Max 99 per item, 50 total in cart. | Required |
| Checkout Step 1 (Address) | Name, phone, full address, state, LGA from ng_lgas_with_areas.ts. No account required. Server-side price re-validation before proceeding to rates. | ng_lgas_with_areas.ts constants file at src/constants/. Cloudflare edge runtime declarations on dynamic pages. | Required |
| Checkout Step 2 (Shipping Rates) | POST /market/checkout/rates → Fez + Sendbox parallel → lowest + 20% buffer per merchant. Grand total shown. Rate cards selectable. | Sendbox: returns data.rate (singular) not data.rates (array). No status field. Floor rates by zone to prevent ₦1,996 Kano anomalies. | Required |
| Checkout Step 3 (Payment) | POST /market/checkout/create → Paystack split (95% merchant / 5% Zerrar) → auth URL OR COD creation. Grand total confirmed. Fee shown if chargeFeeTo = customer. | Paystack fee: 1.5% under ₦2,500; 1.5%+₦100 capped ₦2,000 above. percentage_charge: 5, settlementPercentage: 95.0. | Required |
| Order Success (Paystack) | GET /market/checkout/verify/:ref. Payment confirmed → gold check. Order ref, summary, WhatsApp vendor link, continue shopping. | Redirect from Paystack: /checkout/success?reference=xxx. Verify immediately on page load. | Required |
| Order Success (COD) | COD bypass — no Paystack verification. Warm amber warning banner (pay on delivery). Order ref, delivery ETA, WhatsApp vendor link. | COD success page skips verify entirely. Merchant receives COD order notification. 3 missed COD settlements → account review. | Required |
| Order Tracking | Timeline: placed → confirmed → shipped → out for delivery → delivered. Gold dots = done. Amber = current. Fez/Sendbox webhook drives status updates. | Webhook: x-ship-signature HMAC SHA512 verification. Event types: placed, confirmed, picked_up, in_transit, delivered, failed. | Required |
| Notifications Drawer | Bell icon badge on Dashboard. Bottom sheet overlay (NOT separate screen). Types: New Order, Payment Received, Low Stock, Campaign, Delivery Status. Deep-links per notification. | Bottom sheet overlay — merchant stays in context. Do not route to separate screen. | New |
User Flows
Critical journeys for QA validation — both products.
🛠️ Merchant App Flows
Flow 1 — New Order → Fulfilled (any channel)
FCM Push
→
Order Detail
→
Confirm Order
→
Book Delivery
→
Fez Quote
→
Waybill
→
Tracking Sent
Flow 2 — Add Product + Boost to Ads
FAB +
→
Step 1: Info + Cost Price
→
Step 2: Variants
→
Product Live
→
Profitability Table
→
Boost → /ads?boost=
Flow 3 — Wallet Withdrawal
Wallet Tab
→
Tap Withdraw
→
Enter Amount
→
Bank set?
→
PIN Confirm
→
Transfer Initiated
Flow 4 — Launch Discovery Ad (wallet check)
Ads Tab
→
+ New Campaign
→
Type: Discovery
→
Audience Segment
→
Compose Message
→
Wallet ≥ budget?
→
Campaign Live
Flow 5 — POS Walk-in (Offline)
POS Mode
→
Product Grid (cached)
→
Add to Cart
→
Payment method
→
Receipt
→
Sync on Reconnect
Flow 6 — Free Trial → Paywall
Day 30 Cron
→
Store Paused
→
Paywall Screen
→
Select Plan
→
Paystack Subscription
→
Store Reactivated
🛒 Marketplace Flows
Flow 7 — Customer Discovers & Buys (Paystack)
zerrar.com
→
Browse Category
→
Vendor Profile
→
Product Detail
→
Add to Cart
→
Checkout Step 1 (Address)
→
Step 2 (Rates)
→
Step 3 (Payment)
→
Paystack
→
Order Success
Flow 8 — COD Purchase
Checkout Step 3
→
Select COD
→
POST /market/checkout/create
→
COD Success Page (no verify)
→
Merchant Notified
→
Merchant Confirms
→
Delivery Booked
→
Cash Collected on Delivery
Flow 9 — Multi-Vendor Order
Customer
→
Adds from Vendor A
→
Adds from Vendor B
→
Cart: 2 merchants
→
Checkout
→
Paystack Split (95/5 per merchant)
→
Separate Orders Created per Merchant
Flow 10 — Delivery Tracking Update (Webhook)
Fez Webhook
→
POST /logistics/fez/webhook
→
HMAC SHA512 verify
→
Update Order Status in DB
→
Merchant Notified (FCM)
→
Customer Notified (channel)
Outstanding Fixes (from Testing Feedback)
- ✅ Font consistency — DM Sans 14px uniform all form labels
- ✅ Grid tiles — 2 full columns all screen widths
- ✅ Modals — full-height draggable bottom sheets
- ✅ WebView — back button + loading indicator
- ✅ Auto location — defer to feature trigger only
- ✅ Onboarding images — replace placeholders
- ✅ TextField paste — onInput handler alongside onChange
- ✅ POS offline — 24h product cache + sync on reconnect
- ✅ Code splitting — deferred imports: Expenses/Tax/POS/Profitability
- ✅ FCM token — refresh on foreground event, sync backend
- ✅ Profitability route — /products/profitability BEFORE /products/:id
- ✅ No green — all success/active/confirmed states use gold tokens
- ✅ Positioning — "multi-channel commerce OS", not "WhatsApp-native"
- ✅ Role badge consistency — gold/blue/amber/purple, pixel-identical all screens
Performance Targets
- Cold start to Dashboard: under 2.5s
- POS screen load: under 1s (deferred import)
- Expenses/Tax/Profitability: under 800ms (code split)
- All API calls: 15s timeout + retry once on network error
- Image upload: compress to max 800px before upload
- Animations: all under 300ms, Curves.easeOutCubic
- APK size target: under 25MB
- POS offline cache: valid 24h
- Market page: Core Web Vitals green (Next.js + Cloudflare)
- zerrar.com/blog: useCdn: false (confirmed fix — never revert)
Key Backend Endpoints (Real)
- GET /merchants/profile · GET /merchants/usage
- GET /products · GET /products/low-stock · GET /products/profitability
- GET/PATCH /orders · PATCH /orders/:id/status
- GET /ads/init · POST /broadcasts · GET /broadcasts/init
- GET /merchants/settings (bundle: profile + shipping + notifications)
- POST /market/checkout/rates · /create · GET /market/checkout/verify/:ref
- POST /auth/login · /logout · /refresh
- POST /super-admin/marketers · GET /super-admin/marketers/my/
- POST /logistics/fez/webhook (unguarded, HMAC verify)
- All super-admin routes: /super-admin/ prefix (never /superadmin/)