NeoVerse Docs

Product architecture

How the storefront, API, catalog, and external services fit together.

Product architecture

The browser loads the Next.js storefront from Vercel. The storefront owns page rendering and interaction state, while the Express API owns server-side commerce decisions and protected integrations.

Ownership boundaries

BoundaryOwnerRule
Page rendering and public browsingNext.jsKeep interaction fast and progressively enhanced
Cart and wishlist UI stateZustandTreat it as local presentation state until synchronized
Prices, discounts, tax, shipping, and stockExpress APIThe browser cannot be authoritative
Orders and payment sessionsExpress API and StripeVerify webhook signatures and use idempotency
User identityFirebase Auth and Firebase AdminVerify tokens at the API boundary
Product recordsMongoDB target source of truthDo not let development providers become checkout truth

Current catalog boundary

The public catalog can still use DummyJSON through the Next.js provider layer, while the commerce API reads MongoDB records. Those systems can expose different identifiers, so production checkout is not considered fully reliable until browsing and order flows share one catalog identity.

The intended direction is MongoDB as the production source of truth, with any external seed provider treated as an explicit development or synchronization input.

Design consequence

The frontend should make uncertainty visible rather than papering over it. If a capability, stock value, image, or quote is unavailable, the UI should say so and offer the next useful action.