Frontend Architecture

Route groups, component layers, state management and the typed data layer of the storefront + admin CMS single app.

Diagram v1.3 · Updated 04 Aug 2026, 08:10 GST— Route groups, hook inventory and the typed data layer documented; src/ confirmed as canonical over root symlinks.

Prev Next

100%

Rendering diagram…

Scroll to zoom · drag to pan

1 · Step-by-step workflow

Root shell boots

__root.tsx wraps every route in ShopProvider, AuthProvider, Navbar, Footer, CartDrawer, QuickView and toasters.

File-based route resolves

Flat dot-segment routes under src/routes map to storefront, cart/checkout, account, auth, admin and legal groups.
Admin routes are guarded for ROLE_ADMIN.

Components render from shared layers

Storefront components (ProductCard, ProductGallery, VariantPickers, CollectionView) compose Radix-based ui/ primitives.
Admin CMS editors reuse the same primitives.

Hooks request server state

useProducts, useCategories, useBanners, useBlogPosts, useHomeSections, usePageVisibility, usePolicy, useSiteSettings and useOrderTrackingPoll wrap React Query.

Typed data layer calls the gateway

storefront.ts / commerce.ts / backend-data.ts wrap api.ts, which builds URLs from VITE_API_BASE_URL.
api.ts attaches the JWT (mnm_backend_jwt) when auth: true and throws ApiError otherwise.

State settles

Server state lives in React Query; cart and wishlist in src/store/shop.tsx; session in useAuth.tsx.

2 · Additional details

Stack

React 19 + @tanstack/react-start and @tanstack/react-router on Vite.
Tailwind CSS v4, Radix UI with shadcn-style ui/ components.
react-hook-form + @hookform/resolvers, @tanstack/react-query, Vitest colocated tests.

Data mapping

backend-data.ts (~1.4k lines) centralises DTO → UI-model mapping.
Vite dev proxies /api, /oauth2, /login/oauth2 and /services to http://127.0.0.1:8080.

Conventions

Path alias @/* → src/*; src/ is canonical over the root-level symlinks.
No Redux or Zustand; every non-trivial lib/ module has a colocated *.test.ts.

3 · Advantages & usage

Advantage

Shared design tokens, components and API client — no duplicated UI kit.
One deploy pipeline instead of two frontends.

Usage

Storefront routes are public; admin routes sit behind a ROLE_ADMIN guard.

4 · Phase 2 additions

Remove duplicated root folders

Root hooks/, lib/ and store/ copies are retired in favour of src/.
Resolves the name collision with the Java store service.

Generated typed client

Generate request/response types from a published OpenAPI spec instead of hand-written DTO mappers.

Streaming and route-level caching

Layer SSR streaming and cached loaders onto high-traffic storefront routes.