# Object Router

## Purpose

Top-level frontend URL routes are declared through React Router object configuration instead of inline JSX route declarations.

## Files

- `frontend/src/app/appRoutes.tsx`
- `frontend/src/app/ModuleRouteGuard.tsx`
- `frontend/src/app/shellOutletContext.ts`
- `frontend/src/app/AppRouter.tsx`
- `frontend/src/app/AppProviders.tsx`
- `frontend/src/shared/constants/routes.ts`
- `frontend/src/shared/constants/moduleRoutes.ts`
- `frontend/src/pages/modules/`

## Runtime Shape

- `App.tsx` renders provider composition and the router only.
- `AppProviders` owns global providers, including `BrowserRouter`.
- `AppRouter` renders `useRoutes(appRoutes)`.
- `appRoutes` owns top-level route objects and nested product module routes.
- `APP_ROUTE_PATHS` owns route path constants that are reused outside the router.
- `MODULES` owns module metadata, including each module route path.
- Product route pages are loaded with `React.lazy`.
- `AppLayout` is the shared shell route element and passes shell props through outlet context.
- Module navigation uses route navigation instead of local active-module state.

## Rules

- Do not add individual `<Route>` declarations to `App.tsx`.
- Keep route elements thin; product behavior belongs in business hooks.
- Reuse `APP_ROUTE_PATHS.login` for auth-expired redirects.
- Add route-config and module-route metadata tests when routes change.
- New product modules must define a route path and a lazy page adapter.
- Restricted product routes should redirect to `/dashboard` unless a specific access-state UX is implemented and tested.
- Use object routes as the default pattern unless React Router data APIs require a later move to `createBrowserRouter`.