# Frontend: Route Registration with PageRegistry + DynamicRouter

> **v3.7+** — Replaces the legacy Pattern A (mergeRoutes) and Pattern B (JSX routes) patterns.

---

## How It Works

1. **Backend seed data** defines navigation entries with `ComponentKey` values
   (e.g., `administration.users`, `support.tickets.list`)
2. **`componentRegistry.generated.ts`** registers all page components into `PageRegistry`
   via `PageRegistry.register('key', lazy(() => import(...)))`
3. **DynamicRouter** fetches the menu API, matches each entry's `componentKey` to a
   `PageRegistry` entry, and generates `<Route>` elements at runtime
4. **Implicit routes** (detail, create, edit) are resolved by convention:
   - `*.detail` → `.../:id`
   - `*.create` → `.../create`
   - `*.edit` → `.../:id/edit`

No manual App.tsx wiring is needed.

---

## For SmartStack Core Pages

`componentRegistry.generated.ts` is auto-generated by MCP `scaffold_routes`:

```tsx
// Auto-generated — DO NOT EDIT
import { lazy } from 'react';
import { PageRegistry } from '@/extensions/PageRegistry';

PageRegistry.register('administration.users', lazy(() =>
  import('@/pages/platform/administration/users/UsersPage').then(m => ({ default: m.UsersPage }))
));
PageRegistry.register('administration.users.detail', lazy(() =>
  import('@/pages/platform/administration/users/UserDetailPage').then(m => ({ default: m.UserDetailPage }))
));
// ... ~100 registrations
```

Imported once in `main.tsx`:
```tsx
import './extensions/componentRegistry.generated';
```

---

## For Client SDK Pages

> **CRITICAL:** Keys use DOT notation (`rh.employes.list`), NEVER hyphens (`rh-employes-list`).
> Dots are hierarchy separators matching `NavigationService.ComponentKey` computation at runtime.

Clients register their own pages directly:

```tsx
import { PageRegistry } from '@atlashub/smartstack';
import { lazy } from 'react';

PageRegistry.register('rh.time.dashboard', lazy(() => import('./pages/TimeDashboard')));
PageRegistry.register('rh.time.list', lazy(() => import('./pages/TimeList')));
PageRegistry.register('rh.time.detail', lazy(() => import('./pages/TimeDetail')));
```

Navigation entries are created in DB (via admin UI or seed data).
DynamicRouter does the junction automatically.

---

## Verification

```
Tool: mcp__smartstack__validate_frontend_routes
Args:
  scope: "routes"
```

Checks:
- `componentRegistry.generated.ts` exists
- Each backend NavRoute has a `PageRegistry.register()` call
- `main.tsx` imports the generated file
- Implicit route keys (*.detail, *.create, *.edit) exist for CRUD pages

---

## Legacy Patterns (DEPRECATED)

> The Pattern A (`mergeRoutes(clientRoutes, applicationRoutes)`) and Pattern B
> (JSX `<Route>` in App.tsx) patterns are deprecated since v3.7.
> They still work but are not recommended for new development.
> See git history for the legacy documentation.
