ShopVerse

Overview

ShopVerse demonstrates production-grade ecommerce architecture with a focus on correctness, concurrency, and permission boundaries. The platform separates guest browsing from staff management, with every price and stock decision owned by the server. Payment idempotency handles the webhook/callback race, inventory uses transactional operations, and the audit log captures every sensitive mutation.

Problem

Most portfolio ecommerce projects skip the hard parts: payment idempotency, inventory concurrency under load, server-owned pricing, and RBAC enforcement. Free-tier deployments face budget constraints. A realistic example was needed that demonstrates these production concerns.

Solution

Built ShopVerse with transactional inventory operations (no read-then-subtract races), multi-layer idempotency across checkout/payment/provider transaction/fulfillment, and Paystack webhook + browser callback + background reconciliation all converging on one finalization service. Inventory management includes full stock-movement history. Admin RBAC has ~30 granular permissions enforced server-side. Order line-item snapshots preserve historical correctness.

Key Workflows

• —Hierarchical, admin-managed categories and collections (manual and rule-based)
• —Admin-composed homepage with section engine (rails, grids, campaigns, scheduling)
• —Composable filters with URL state (shareable, back-button-safe, live counts)
• —Cursor-paginated infinite discovery with IntersectionObserver prefetch
• —Guest cart with client-only intent (productId, variantId, quantity) → server calculates totals
• —Inventory reservations with transactional, conditional stock operations
• —Multi-layer idempotency: checkout → payment ref → provider transaction → fulfillment
• —Payment and order state machines (never a paid = true boolean)
• —Webhook + browser callback + background reconciliation on one finalization service
• —Non-enumerable public order references (SV-A7K92M4P) separate from internal UUIDs
• —Order line-item snapshots for historical invoice correctness
• —Backoffice: product editor, inventory with stock-movement history, payments dashboard with reconciliation queue
• —Staff invitations with hashed, single-use, expiring tokens
• —Append-only audit log on every sensitive mutation
• —Analytics: revenue, AOV, conversion funnel, top products, zero-result searches

Technical Decisions

• —Used Drizzle ORM with typed schema and migrations for database safety and versioning
• —Chose Neon PostgreSQL for transactional integrity and concurrent stock operations
• —Paystack for payments with server-side init and HMAC-SHA512 webhook verification
• —TanStack Query for client state (infinite queries, polling, optimistic updates)
• —Cloudinary for media with metadata in Postgres, binaries never in DB
• —Tag-based cache invalidation (product:{id}, homepage, offers) with hard public/private boundary
• —HTTP-only session cookies, honeypots, rate limiting, CSP and security headers
• —Database-backed RBAC: ~30 granular permissions, 6 roles, enforced server-side
• —Intentionally lean: 8 runtime dependencies total

Performance

Layout-matching skeletons and empty states throughout for perceived performance. Cursor pagination with IntersectionObserver prefetch for infinite discovery. Tag-based cache invalidation for immediate consistency without stale data. Cloudinary for responsive image delivery. Debounced global search with suggestions and recent searches.

Accessibility

WCAG 2.2 AA target throughout. Structured data for SEO (Product schema, BreadcrumbList). Semantic HTML with proper heading hierarchy. Keyboard navigation for filters, cart, and checkout. Sufficient color contrast on all interactive elements. Error boundaries and empty states with clear messaging.

Stack

Role: Full-stack developer