Skip to main content

Routing

All routing lives in one file: frontend/src/App.tsx. There is no file-based routing and no route config objects — a single <BrowserRouter><Routes> tree using the unified react-router v7 package (the app imports from react-router, not react-router-dom).

The three route trees​

  1. ERP app — everything from /dashboard to /inventory/* sits inside ProtectedRoute (login required, redirects to /login carrying state.from) and AppLayout (sidebar + header shell). Most pages are additionally nested under RequirePermission — see auth-and-permissions.md for guard semantics, including the deliberate /billing/success exception.

  2. Public marketing site — PublicLayout (header + footer, no auth): home, about, solutions, pricing, FAQ, privacy/terms, and the public careers pages (/careers, /careers/:id, /careers/:id/apply). The careers page components live in pages/recruitment/ because they feed the recruitment module, but they are routed publicly.

  3. Customer portal — the sign-in pages (login, register, forgot and reset password, verify email) sit outside every layout and use the same full-screen AuthCardLayout as /login. Everything else is inside PortalLayout, which guests see too: the home page, catalog and product pages are public, so a visitor can browse prices and stock status before having an account. The account pages (cart, checkout, orders, wishlist, stock alerts, profile) are nested in PortalProtectedRoute: a direct link sends a guest to /portal/login?next=<page> and back after signing in.

    Inside the storefront, anything that needs an account (Add to cart, the wishlist heart, Notify me, the cart button, Orders) goes through useRequirePortalAuth: a guest gets the sign-in dialog (PortalAuthDialog, mounted once in the layout) instead, and what they clicked is saved (components/portal/auth/intent.ts) and finished for them once they are signed in — straight away, or after the confirmation email for a new account, which brings them back to the page they registered from. The account hooks (usePortalCart, usePortalWishlist, …) are disabled for guests, so the shell never calls an account endpoint without a token. The portal has a completely separate auth system (auth-and-permissions.md §Portal).

A catch-all <Route path="*"> renders the lazy NotFound page. Two convenience redirects exist: /crm → /crm/dashboard and /inventory → /inventory/dashboard.

Lazy loading and the page() helper​

Every page is loaded with React.lazy(() => import(...)) so each route becomes its own chunk. (One historical exception: GovernmentForms is imported eagerly at the top of App.tsx.) Instead of one <Suspense> around the whole tree, each route element is produced by the page() helper:

const page = (Component: ComponentType) => (
<RouteErrorBoundary>
<Suspense fallback={<LoadingFallback />}>
<Component />
</Suspense>
</RouteErrorBoundary>
);

The per-route boundary is deliberate. As the comment in App.tsx explains: with React Router v7 + React.lazy, a single Suspense wrapping the whole <Routes> tree can leave the previous route's content on screen after the URL has already changed while the next chunk loads — a transition quirk of the combination. Giving each route its own boundary means navigation immediately swaps to the loading fallback and stays responsive. Each page also gets its own RouteErrorBoundary, so a crash in one page doesn't blank the shell.

Route constants​

Paths are never string literals in components — they come from the ROUTES object in constants/routes.ts (ROUTES.EMPLOYEES, ROUTES.PAYROLL_RUN_DETAIL = '/payroll-runs/:id', …). Navigation uses the same constants, so renaming a path is a one-line change.

How to add a page​

  1. Create the page component under frontend/src/pages/<domain>/MyPage.tsx (default export — React.lazy requires it).
  2. Add a path constant to constants/routes.ts.
  3. Register the route in App.tsx: add a const MyPage = lazy(() => import('./pages/<domain>/MyPage')) and a <Route path={ROUTES.MY_PAGE} element={page(MyPage)} /> under the correct layout (ERP pages go inside ProtectedRoute → AppLayout).
  4. Gate it: wrap in <Route element={<RequirePermission permission={PermissionConstants.…} />}> — pass an array for OR semantics. Permission strings must mirror the backend's @PreAuthorize constants via constants/permissions.ts.
  5. Add navigation: add a NavItem (icon, label, to, permission, optional roleContext) to ui/layout/nav-config.ts so the sidebar shows it to the right users.
  6. If the page needs a brand-new permission, remember the frontend's static role map must be updated too — see the sync gotcha in auth-and-permissions.md.

For a worked full-stack example of an existing page, read ../learn/employees-walkthrough.md.