TrustStoreFront — Multi-Tenant Storefront Platform
A production storefront supporting three distinct retail topologies — single store, single store with branches, and multi-store with per-branch catalogs — resolved at runtime from backend store configuration. The architecture is built around a fork-based brand model: a canonical skeleton repo holds all infrastructure and business logic; each brand maintains its own fork that customizes only the visual layer and syncs upstream skeleton releases via tagged merges. Built with Server Components by default, server actions for all mutations, cookie-driven state for branch/auth/guest identity, and full SEO infrastructure (dynamic metadata, JSON-LD, sitemap, robots, RTL support for Arabic).
Overview
White-label e-commerce storefront skeleton powering multiple branded sites from a single codebase; companion to TrustDashboard admin panel.
Key Challenges
- Next.js 16 migration realities: Async params/searchParams/cookies()/headers(), cacheComponents: true, and the new 'use cache' directive, codified rules for when reads use 'use cache' (request-independent) vs 'use server' (per-user, to prevent cross-user data leaks).
- State without a client store: Replaced a Zustand layer with cookies-as-source-of-truth + React Context providers re-hydrated on every server render. Mutations call revalidatePath and providers propagate fresh values, no client-side cache to invalidate. React Query is scoped only to cart and store-online polling.
- Multi-tenancy without runtime overhead: Chose fork-per-brand over a runtime theming engine to keep bundles minimal and let each brand evolve independently, required formalizing which files are skeleton vs brand-customizable, and a release/merge protocol to keep divergence manageable.
Key Achievements
- Designed a layered clean architecture (presentation / application / domain / infrastructure) with strict file-per-unit rules across 13 core features (products, categories, offers, branches, cart, checkout, auth, profile, …).
- Skeleton + brand-fork system: reduced new brand onboarding from 2 weeks to 2 days
- SEO foundation: dynamic generateMetadata per route, structured data (Organization, WebSite, Product, BreadcrumbList JSON-LD), dynamic sitemap from product catalog, locale-aware canonical and hreflang tags.
- Module resolver pattern (module-resolver.tsx) that dynamically composes core features into store-type-specific page layouts, keeping app/ routes as ~10-line delegation shells.
- Full i18n pipeline (English/Arabic, RTL via Radix DirectionProvider) with locale resolved from the URL segment as the single source of truth, and backend *_ar/*_en field resolution moved into mappers so domain models stay locale-clean.
- ActionResult<T> contract for server mutations — solved Next.js production error sanitization by replacing thrown errors with typed result objects, enabling reliable backend message surfacing in toasts and inline field errors.