SpazaLink
Full shelves. Safe stock. Bank ready.
SpazaLink is a B2B web app for South African township spaza shops. It links shops to verified wholesalers, tracks their stock, and turns their trading history into a Financial Health Report they can take to a bank.
The idea comes from Rethabile Madonsela (founder and idea owner).
It's a live app that processes real user data against MongoDB Atlas, with sign-in handled by Clerk. Nothing in it is a static mock-up.
| Screen | What it does |
|---|
Inventory Dashboard (/dashboard) | Compliance score that updates as CIPC, BEE and tax documents are uploaded or removed. Colour-coded stock tracker. A low-stock alert slides down when an item drops into Red. Quick Fix adds the missing quantity to the cart and opens checkout. |
Ordering & Checkout (/order) | A catalogue of verified products only, each with SABS / Verified Supplier badges. The cart shows bulk discounts as a separate line. Payment toggles are PayShap, Instant EFT and Cash on Delivery. A live delivery timeline follows each order. |
Financial Portal (/finance) | Monthly spend chart and bank scorecard (total spent, on-time payments, credit health), plus a one-tap Financial Health Report PDF with the SpazaLink logo. |
Quick start
npm install
cp .env.example .env.local # fill in MONGODB_URI and REPORT_SIGNING_SECRET
npx clerk@latest env pull # writes the Clerk keys for the linked "Spaza Link" app
npm run seed # wholesalers, catalogue, two demo shops + their Clerk users, sample PDFs
npm run dev # http://localhost:3000
Before you submit, run the security checks against a production build:
npm run build && npm start # terminal 1
npm run test:brief # terminal 2: 80 checks, one per item in the project brief (writes BRIEF_TEST_REPORT.md)
npm run test:security # terminal 2: 66 security, role, demo shop and data wall checks
Windows clock. Clerk rejects session tokens that look "issued in the future". If your PC clock is more than a few seconds off, sign-in loops back to the sign-in page. Sync it under Settings → Time & language → Date & time → Sync now.
Demo accounts (for the slides)
If Clerk asks for a verification code, enter 424242. That code works for any +clerk_test address on a development instance. The same accounts are shown on the sign-in page with copy buttons.
Thandi's shop is preloaded with stock in all three colours, six months of orders, and CIPC + BEE documents (85% Ready). Sipho's shop has no documents, so you can demo uploads live with samples/sample_cipc_certificate.pdf and samples/sample_bee_affidavit.pdf. Run npm run seed again at any time to reset both demo shops. It also resets the demo users' passwords in Clerk.
What the seed loads
- 8 shops. Thandi and Sipho have logins. Six community shops (Tembisa, Mamelodi, Alexandra, Umlazi, Soshanguve and Mdantsane) have data only, so the admin graphs have a real network to show.
- 7 wholesalers: five verified, one pending and one rejected.
- 47 products across nine categories. Three are unverified, which proves the safety gate.
- About 117 stock lines and 140 orders over six months, with payments, delivery timelines and compliance documents. A few late payers make the credit health scores vary.
Demo shop for everyone
Thandi's Spaza is the shared demo shop (isDemo: true in the seed).
- No shop yet: anyone signed in without their own shop sees it by default. A welcome popup and a banner explain this and offer Register my own shop.
- View only: the server refuses every change made in demo mode with 403
DEMO_READ_ONLY.
- After registering: the new owner sees only their own shop, which starts empty, with no demo data mixed in. Shop owners can still peek at the demo with the Demo shop button in the header.
- Data walls stay intact: only the shop marked as the demo is ever shared. Every other shop stays walled, and the security suite checks this.
Admin portal (/admin)
Open to the Platform admin role only. The role is stored in the Clerk user's publicMetadata.role and checked on the server for every admin request. Everyone else gets an "Admins only" screen, and the API answers 403.
| Page | What it shows | Forms and actions |
|---|
| Overview | Key figures, registrations per month, newest shops, order value, orders, deliveries by status, payment mix, best sellers, sales by category, stock health per shop, credit health, compliance, critical stock, recent orders | Platform report download (PDF or PowerPoint) |
| Shops | Every shop with joined date, compliance, a stock-health bar, orders, spend, on-time rate and credit health. Includes credit health and compliance charts | Select a shop for its monthly spend chart |
| Orders | Every order with payment outcome. Includes a status donut and payment outcome chart | Status tabs, search, Move on (advances delivery) |
| Products | The catalogue, with a status donut and products per category | Add product, with a live price check chart against its category. Edit price, bulk deal and verification |
| Suppliers | Every wholesaler, with a status donut, wholesalers per province and order value per wholesaler | Add supplier, with a live province chart. Change verification inline |
| Guide | A plain-language explanation of how SpazaLink works | |
All charts are shadcn/ui charts (src/components/charts.tsx).
When anyone signs in, a one-time notice explains that access is role based today, and that full RBAC is coming: named permissions per role, with an audit trail.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
