(05)
Stockfront
A storefront out front, an inventory engine in the back.
- Year
- 2026
- Role
- Full-stack Engineer
- Stack
- Next.js 16 · Prisma 7 · Paystack · PostgreSQL
(01) Overview
Stockfront is the commerce platform I built end to end for a Nigerian tools-and-machinery importer — the storefront customers buy from, and the operations platform the team runs the business on, in one Next.js codebase.
Customers browse, pay in naira through Paystack and track orders. Staff manage the catalog, a stock ledger, fulfilment, homepage content and analytics — with four role tiers deciding who sees what, down to finance numbers only the owner can open.
(02) The Challenge
Commerce is where correctness gets expensive: payments confirmed by two racing signals (webhook and browser redirect), stock that must decrement exactly once, staff and customers sharing one browser, and supplier product photos too messy to put on a storefront.
(03) Architecture — and why
One codebase, two applications
Storefront and admin live in the same Next.js project, split by route groups and sharing one Prisma schema — gated by a route-level proxy plus per-action role guards, so there's defense in depth without a second deployment.
Two auth instances, namespaced cookies
Customers and staff authenticate against separate NextAuth instances with fully namespaced cookies — a shopper and an admin can be signed in simultaneously in the same browser without stomping each other's sessions.
A server-authoritative money path
Checkout recomputes totals on the server, verifies payment against Paystack directly, and confirms inside one idempotent transaction — safe to call twice, whichever of the webhook or redirect lands first.
Server actions, no client data layer
Data flows down as RSC props and back up through server actions with targeted revalidation — no query library, no client cache to invalidate, far less to go wrong.
RBAC as a matrix, not if-statements
Four roles by ten admin sections with none/view/edit grants, checked isomorphically — the finance view simply doesn't exist unless you're the super admin.
(04) Engineering Highlights
A photo lab in the save button
Supplier images get flood-fill background removal (bailing out on real photos), auto-trim, Lanczos upscaling and WebP re-encode via sharp — paste any URL, get a clean catalog image. SSRF-guarded fetching included.
Payments that can't double-fire
The Paystack webhook and the customer's redirect both race to confirm an order; an atomic claim pattern means stock decrements exactly once, no matter who wins.
Inventory as a ledger
Every stock change is a movement record — restock, online sale, offline sale, adjustment — written in the same transaction as the update, with reorder-level alerts on the dashboard.
A Zod-schema'd CMS
Hero, banners, stats and testimonials live as typed JSON settings — one schema validates the seed data, the storefront read and the admin editor, so the homepage can't drift from its contract.
Drafts for the ops team
Half-finished product edits autosave per staff member, fully isolated from the live catalog — a reload never loses work, and a draft can never leak to the storefront.
Hand-rolled search that feels right
A relevance scorer weights name-prefix over brand over description matches, with full keyboard navigation — plus a filter browser whose price ceiling derives from the actual catalog.
(05) The Flow
- 01
Customer browses, filters and searches the catalog
- 02
Checkout recomputes totals server-side and opens Paystack
- 03
Webhook and redirect reconcile; stock decrements exactly once
- 04
Orders flow into fulfilment — analytics and low-stock alerts follow
(06) Impact
1
codebase running storefront + operations
13
data models behind the commerce flow
4-role
RBAC across ten admin sections