Skip to content
BabyMartBabyMart

Storefront

The customer shop in apps/web — every route, the main features, its state stores and how it talks to the API.

The Storefront is the shop customers use. They browse products, add items to a cart, check out with Stripe, SSLCommerz or cash on delivery, and follow their orders from a personal dashboard. Sellers can also apply to become a vendor and manage their own products here. It is a Next.js App Router app in apps/web, served on port 3000.

At a glance

Section titled “At a glance”

Who uses it

Shoppers (role user), plus vendors managing their own products.

Built with

Next.js 16, React 19, Tailwind CSS v4, Zustand, Stripe.js, Firebase Auth. See Tech stack.

Size

52 pages, 3 API route handlers, and 3 metadata routes (sitemap, manifest, OG image).

Entry points

apps/web/app/layout.tsx and apps/web/proxy.ts

The shopping journey

Section titled “The shopping journey”
  1. 1BrowseHome, shop, search
  2. 2Product/product/[id]
  3. 3Cart/user/cart
  4. 4CheckoutAddress + method
  5. 5PayStripe, SSLCommerz or COD
  6. 6Confirmed/success
From the home page to a paid order. The payment steps are explained on the Payments page.

Placing an order calls POST/api/orderscreateOrderFromCart(). For a card payment, the storefront’s own route handler then creates a Stripe Checkout Session. Payments covers the full flow, including the webhook and the success page.

Route map

Section titled “Route map”

Route groups in parentheses, such as (client), organise the files without changing the URL.

flowchart LR
  A["(auth)"] --> A1["/auth/*"]
  C["(client)"] --> P["(public) — shop, product, blog, help"]
  C --> U["(user) — /user/*, /success"]
  C --> V["(vendor) — /vendor/*, /become-vendor"]
  API["app/api"] --> R["checkout session · stripe webhook · oauth"]

Auth

Section titled “Auth”
Route What it does
/auth/signin Email and password sign-in, plus Google and GitHub buttons
/auth/signup Create an account (does not sign you in)
/auth/forgot-password Request a reset link
/auth/reset-password Set a new password from the emailed link

Public

Section titled “Public”
Route What it does
/ Home page: banners, product-type sections, blog strip, vendor call-out, all products
/shop Product grid with filters and pagination
/product/[id] Product detail. An id URL redirects to the slug URL. Adds Product JSON-LD
/product-base/[slug] A curated product collection
/categories All categories
/compare Side-by-side comparison of up to 4 products
/search Search landing page
/blog, /blog/[slug] Blog list and post (HTML sanitised before render)
/[...slug] CMS pages built in the admin, revalidated every 5 minutes
/about, /faq, /help, /help/contact, /help/shipping, /privacy, /terms, /returns, /testimonials, /programs, /others Static content pages

Customer account (signed in)

Section titled “Customer account (signed in)”
Route What it does
/user/cart, /user/checkout, /user/wishlist Cart, checkout and saved items
/user/dashboard, /user/profile, /user/settings Account overview and settings
/user/orders, /user/orders/[id] Order history and detail, with “Pay Now” for unpaid orders
/user/analytics, /user/notifications Spending charts and in-app notifications
/success Order confirmation after payment

Vendor

Section titled “Vendor”
Route What it does
/become-vendor, /vendor-guide Apply to sell, and the seller guide
/vendor, /vendor/products Vendor dashboard and product management
/vendor/orders, /vendor/analytics, /vendor/settings Placeholder “coming soon” pages

API route handlers

Section titled “API route handlers”
Handler Purpose
POST /api/create-checkout-session Builds a Stripe Checkout Session from an orderId
POST /api/stripe-webhook Verifies the Stripe signature and tells the API the order is paid
POST /api/auth/oauth Forwards a whitelisted OAuth payload to the API

Key features

Section titled “Key features”

Shop filters

Category, brand, product type, vendor, price range, rating, colours, sizes and discount, with grid or list view and numbered pages.

Search

Debounced text search (300 ms) and search by image, which matches an uploaded photo by dominant colours.

Wishlist, compare, reviews

A server-backed wishlist, a compare list of up to 4 products stored in the browser, and product reviews that an admin approves.

Display currency

Prices can be shown in 12 currencies using fixed rates. Display only; orders are charged in the store currency.

Vendors

The whole vendor area switches on or off from the API’s vendor config.

SEO

Per-page metadata, Open Graph image route, JSON-LD (Organization, WebSite, Product), sitemap.ts and a web manifest.

AI assistant

Section titled “AI assistant”

A round teddy-bear button sits above the shopping-bag Buy Turbo BabyMart button on every page except checkout. Hovering it shows a “Hi! Click to chat” chip, and clicking it opens the chat. It answers questions about shopping on the store and about the BabyMart product (features, apps, stack, setup and purchase).

  • POST /api/assistant streams newline-delimited JSON. With ANTHROPIC_API_KEY set, it asks Claude, using a cached system prompt that holds the whole knowledge base plus a live snapshot of categories, brands and blog posts.
  • Guests get 5 AI replies a day and signed-in customers 20. The count is kept in a signed cookie and in memory per IP or user.
  • After the limit, without a key, or if Claude fails, the same route answers from the knowledge base with a local BM25 search, so the chat never stops working.
  • Edit the answers in lib/assistant/knowledge.ts and the starter chips in lib/assistant/suggestions.ts.
apps/web/app/api/assistant/route.ts apps/web/lib/assistant/knowledge.ts

State

Section titled “State”

All stores use Zustand. Persisted stores save to localStorage.

Store Holds Persisted as
useUserStore Signed-in user, token, sign-in helpers user-storage (user only)
useCartStore Server-backed cart cart-storage
useOrderStore The user’s orders order-storage
useWishlistStore Wishlist items wishlist-storage
useCurrencyStore Selected display currency currency-storage
useCompareStore Up to 4 products to compare compare-storage
useNavStore Menus and category tree, cached for 10 minutes nav-storage
useHeaderStore, useModalStore UI flags (auth sidebar, modals) not persisted

apps/web/lib/store.ts holds the first five; the rest live in apps/web/store/.

Talking to the API

Section titled “Talking to the API”
  • apps/web/lib/config.ts builds every URL with an /api prefix. In the browser it uses NEXT_PUBLIC_API_URL. On the server it prefers API_ENDPOINT. See Environment variables.
  • The sign-in token lives in an auth_token cookie (7 days) and is sent as Authorization: Bearer ….
  • apps/web/proxy.ts guards /user/*, /auth/* and /success. It verifies the token with GET/api/auth/profile. Signed-out visitors go to /auth/signin?redirect=…. Signed-in visitors are sent away from the auth pages. Details: Auth and roles.
Section titled “Related pages”
PaymentsStripe Checkout, SSLCommerz, COD and the webhook.
Admin dashboardWhere the catalog, CMS pages and orders are managed.
API endpointsEvery endpoint the storefront calls.
Shared packagesTypes, UI components and design tokens.