@atlashub/smartstack-cli 4.31.0 → 4.33.0

package/templates/skills/apex/references/frontend-route-wiring-app-tsx.md

@@ -1,162 +1,70 @@
-# Frontend: Route Wiring in App.tsx
+# Frontend: Route Registration with PageRegistry + DynamicRouter
 
-> Referenced from `steps/step-03-execute.md` — Detailed route wiring patterns and verification.
+> **v3.7+** — Replaces the legacy Pattern A (mergeRoutes) and Pattern B (JSX routes) patterns.
 
 ---
 
-## Step 4: Wire Routes to App.tsx
+## How It Works
 
-**Important:** This step is required. Without it, routes exist as files but are invisible to the React Router. The page will be blank.
+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`
 
-After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`.
+No manual App.tsx wiring is needed.
 
 ---
 
-## Step 4a: Import Page Components (Lazy Loading ONLY)
+## For SmartStack Core Pages
 
-At the top of App.tsx, ALL page imports MUST use `React.lazy()`:
+`componentRegistry.generated.ts` is auto-generated by MCP `scaffold_routes`:
 
 ```tsx
-// CORRECT — Lazy loading (MANDATORY per POST-CHECK S6)
-const {EntityName}Page = lazy(() =>
-  import('@/pages/{Application}/{Module}/{EntityName}Page')
-    .then(m => ({ default: m.{EntityName}Page }))
-);
-
-// WRONG — Static import is BLOCKING per POST-CHECK S6
-// import { {EntityName}Page } from '@/pages/{Application}/{Module}/{EntityName}Page';
+// 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
 ```
 
----
-
-## Step 4a.5: Import Generated Route Extensions (if scaffold_routes was used)
-
-If `scaffold_routes` generated `applicationRoutes.generated.tsx`, import and spread:
-
+Imported once in `main.tsx`:
 ```tsx
-import { applicationRouteExtensions } from '@/routes/applicationRoutes.generated';
-
-const applicationRoutes: ApplicationRouteExtensions = {
-  ...applicationRouteExtensions,
-  // additional manual routes if needed...
-};
+import './extensions/componentRegistry.generated';
 ```
 
-If no generated file exists, add routes directly to the existing `applicationRoutes` object.
-
 ---
 
-## Step 4b: Detect App.tsx Routing Pattern
-
-Read App.tsx and detect which pattern is used:
+## For Client SDK Pages
 
-### Pattern A: applicationRoutes Object
-
-**If App.tsx contains:** `applicationRoutes: ApplicationRouteExtensions`
-
-→ Add routes to `applicationRoutes.{application}[]` with **RELATIVE** paths (no leading `/`)
-
-> **CRITICAL — Include Module Segment:** Paths are relative to `/{application}/`.
-> For a 3-level hierarchy (app → module → sections), paths MUST be `{module_kebab}/{section_kebab}`.
-> Using just `{section_kebab}` omits the module segment → route resolves to `/{app}/{section}` instead
-> of `/{app}/{module}/{section}` → mismatch with backend navigation seed data → 404.
+Clients register their own pages directly:
 
 ```tsx
-const applicationRoutes: ApplicationRouteExtensions = {
-  'human-resources': [
-    // existing routes...
-    // Paths include module segment: employee-management/employees (NOT just employees)
-    { path: '{module_kebab}/{section_kebab}', element: <{EntityName}ListPage /> },
-    { path: '{module_kebab}/{section_kebab}/create', element: <Create{EntityName}Page /> },
-    { path: '{module_kebab}/{section_kebab}/:id', element: <{EntityName}DetailPage /> },
-    { path: '{module_kebab}/{section_kebab}/:id/edit', element: <Edit{EntityName}Page /> },
-
-    // Parent redirect routes (MANDATORY — prevents /login redirect on parent navigation)
-    { path: '{module_kebab}', element: <Navigate to="{module_kebab}/{first_section_kebab}" replace /> },
-    { path: '', element: <Navigate to="{first_module_kebab}/{first_section_kebab}" replace /> },
-  ],
-};
-
-// Concrete example: app=human-resources, module=employee-management, sections=employees,absences
-const applicationRoutes: ApplicationRouteExtensions = {
-  'human-resources': [
-    { path: 'employee-management/employees', element: <EmployeesPage /> },           // ✅
-    { path: 'employee-management/employees/create', element: <CreateEmployeePage /> }, // ✅
-    { path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },   // ✅
-    // ...absences...
-    { path: 'employee-management', element: <Navigate to="employee-management/employees" replace /> },
-    { path: '', element: <Navigate to="employee-management/employees" replace /> },
-  ],
-};
-
-// ❌ WRONG — missing module segment:
-// { path: 'employees', ... }  → resolves to /human-resources/employees (backend expects /human-resources/employee-management/employees)
-```
-```
-
-Routes are automatically injected into BOTH standard (`/{application}/...`) and tenant-prefixed (`/t/:slug/{application}/...`) route trees by `mergeRoutes()`. No manual duplication needed.
-
-#### Custom Applications (Pattern A)
+import { PageRegistry } from '@atlashub/smartstack';
+import { lazy } from 'react';
 
-Custom application keys (any key **not** in the built-in list: `administration`, `support`, `user`, `api`) are fully supported in `applicationRoutes`. `mergeRoutes()` automatically:
-
-1. Creates a new route entry wrapped in `<AppLayout />`
-2. Injects it into **both** standard (`/{app-key}/...`) and tenant-prefixed (`/t/:slug/{app-key}/...`) trees, inside `TenantRouteWrapper > RouteGuard > LicenseGuard`
-3. Generates automatic parent redirect routes (e.g., `employees` → `employees/management`)
-
-No need to use Pattern B for custom applications — Pattern A handles everything automatically.
-
-### Pattern B: JSX Routes
-
-**If App.tsx contains:** `<Route path="/{application}" element={<{Layout} />}>`
-
-→ Insert `<Route>` children inside the Layout wrapper:
-
-```tsx
-<Route path="/human-resources" element={<AppLayout />}>
-  {/* ... existing routes ... */}
-  <Route path="{module_kebab}" element={<{EntityName}Page />} />
-</Route>
+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')));
 ```
 
-**ALSO add the same routes inside the tenant-prefixed block:**
-
-Find `<Route path="/t/:slug">` and add the **same route entries** there.
+Navigation entries are created in DB (via admin UI or seed data).
+DynamicRouter does the junction automatically.
 
 ---
 
-## Step 4b.5: Verify mergeRoutes() Call
-
-**Before modifying routes, READ App.tsx and verify the `mergeRoutes()` call has 2 parameters.**
-
-✅ Correct:
-```tsx
-const routes = mergeRoutes(clientRoutes, applicationRoutes);
-```
-
-❌ If you see only 1 parameter:
-```tsx
-const routes = mergeRoutes(clientRoutes);
-```
-
-→ Add the `applicationRoutes` object and pass it as 2nd parameter.
-Without it, all application routes are silently ignored → blank page or /login redirect.
-
-**Do not remove the `applicationRoutes` parameter or the `ApplicationRouteExtensions` import.**
-
----
-
-## Step 4c: Application-to-Layout Mapping
-
-| Application prefix | Layout Component | Route path |
-|---------|------------------|------------|
-| `administration.*` | `AppLayout` | `/administration` |
-| `*` (business apps) | `AppLayout` | `/{application}` |
-| `myspace.*` | `AppLayout` | `/myspace` |
-
----
-
-## Step 4d: Verify Wiring
+## Verification
 
 ```
 Tool: mcp__smartstack__validate_frontend_routes
@@ -164,68 +72,17 @@ Args:
   scope: "routes"
 ```
 
-If `appWiring.issues` is not empty, fix the wiring before proceeding.
-
----
-
-## Step 4e: Parent Redirect Routes
-
-**Important:** Without parent redirects, navigating to an application or module URL (e.g., `/human-resources` or `/human-resources/employees`) will cause a redirect to `/login` because no route matches.
-
-For each application, add:
-
-1. **Application root redirect** — redirects `/{application}` to the first module/section:
-   ```tsx
-   { path: '', element: <Navigate to="{first_module}/{first_section}" replace /> }
-   ```
-
-2. **Module redirect** (if modules have sections) — redirects `/{application}/{module}` to first section:
-   ```tsx
-   { path: '{module}', element: <Navigate to="{module}/{first_section}" replace /> }
-   ```
-
-**Example:** For NavRoutes `human-resources.employee-management.employees` and `human-resources.employee-management.absences`:
-```tsx
-{ path: 'employee-management', element: <Navigate to="employee-management/employees" replace /> },
-{ path: '', element: <Navigate to="employee-management/employees" replace /> },
-```
-
-The `to` prop is resolved relative to the **parent route** (`/{application}`), so always use the full path from the application root.
-
-> Note: `scaffold_routes` with `outputFormat: "applicationRoutes"` generates these redirects automatically.
-
----
-
-## Patterns to Avoid (BOTH patterns)
-
-- Do not add application routes to `clientRoutes[]` with absolute paths — `clientRoutes` is only for routes outside SmartStack applications (e.g., `/about`, `/pricing`)
-- Do not add routes outside the Layout wrapper (shell will not render)
-- Do not use `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
-- Do not add custom application routes to `clientRoutes[]` with absolute paths:
-  ```tsx
-  // ❌ WRONG — bypasses RouteGuard + TenantLayout + AppLayout → /login redirect
-  const clientRoutes: RouteConfig[] = [
-    { path: '/human-resources/employees/management', element: <EmployeePage /> },
-  ];
-  ```
-  Custom application routes go in `applicationRoutes` with RELATIVE paths (including module segment):
-  ```tsx
-  // ✅ CORRECT — module segment included
-  const applicationRoutes: ApplicationRouteExtensions = {
-    'human-resources': [
-      { path: 'employee-management/employees', element: <EmployeesPage /> },
-    ],
-  };
-  ```
-- Do not remove the `applicationRoutes` 2nd parameter from `mergeRoutes()` — this silently breaks all custom 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
 
 ---
 
-## Verification Checklist
+## Legacy Patterns (DEPRECATED)
 
-- [ ] Routes are inside the AppLayout wrapper
-- [ ] Routes use NESTED structure (not flat)
-- [ ] Application kebab-case matches navigation seed data
-- [ ] Both standard and tenant-prefixed blocks have routes (if using Pattern B)
-- [ ] Page components are imported at top of App.tsx
-- [ ] `mcp__smartstack__validate_frontend_routes` returns no issues
+> 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.

package/templates/skills/apex/references/parallel-execution.md

@@ -98,14 +98,26 @@ Layer 2 (Backend) — if multiple entities:
   # Launched in parallel in a single message
 
 Layer 3 (Frontend) — if multiple entities:
+  # ⛔ AGENT BOUNDARY: Snipper agents do NOT have access to Skill().
+  # Pages (.tsx) MUST be generated by the principal agent via Skill("ui-components").
+  # Snipper agents handle ONLY: API clients, routes, wiring, i18n — NOT pages.
+
+  # PHASE A — Parallel: infrastructure (Snipper agents)
   Agent(subagent_type='Snipper', model='opus',
-    prompt='Execute Layer 3 frontend for {Entity1}: pages, i18n, routes...')
+    prompt='Execute Layer 3 INFRASTRUCTURE for {Entity1}: API client, routes, wiring, i18n.
+            DO NOT generate any .tsx page files — pages are handled by the principal agent.')
   Agent(subagent_type='Snipper', model='opus',
-    prompt='Execute Layer 3 frontend for {Entity2}: pages, i18n, routes...')
+    prompt='Execute Layer 3 INFRASTRUCTURE for {Entity2}: API client, routes, wiring, i18n.
+            DO NOT generate any .tsx page files — pages are handled by the principal agent.')
   # Launched in parallel in a single message
+
+  # PHASE B — Sequential: pages (principal agent only)
+  # After all Snipper agents complete, principal generates pages via Skill("ui-components").
+  # See step-03-execute.md Layer 3 HARD RULE for full protocol.
 ```
 
 Each agent has an **isolated scope**: handles one entity end-to-end within the layer.
+**Exception:** Layer 3 pages are NOT delegated — see step-03 HARD RULE.
 
 ---
 
@@ -129,8 +141,9 @@ Each agent has an **isolated scope**: handles one entity end-to-end within the l
 5. Layer 2: launch Snipper agents per entity (if multi-entity) OR agent principal (if single)
 6. Build gate: dotnet build → MUST PASS
 7. Backend tests inline (scaffold + run + fix max 3)
-8. Layer 3: launch Snipper agents per entity (if multi-entity) OR agent principal (if single)
-9. Compliance gate: 5 frontend checks → MUST PASS
+8. Layer 3 Phase A: launch Snipper agents for infra (api-client, routes, i18n) — NOT pages
+9. Layer 3 Phase B: principal agent generates ALL pages via Skill("ui-components") — sequential
+10. Compliance gate: 6 frontend checks → MUST PASS
 10. Frontend tests inline (scaffold + run + fix max 3)
 11. Layer 4 (optional): agent principal executes DevData
 ```
@@ -151,6 +164,6 @@ There is no idle state to manage — the agent principal simply waits for result
 | economy_mode = true | NO parallel agents, all sequential |
 | Single entity (any layer) | NO parallel agents, agent principal handles all |
 | Multiple entities, Layer 2 | Parallel: one Snipper agent per entity (service + controller) |
-| Multiple entities, Layer 3 | Parallel: one Snipper agent per entity (pages + i18n) |
+| Multiple entities, Layer 3 | Parallel: Snipper agents for infra (api-client, routes, i18n) — pages by principal via Skill("ui-components") |
 | Layer 0, Layer 1, Layer 4 | NO parallel agents (sequential by nature) |
 | Analysis phase (step-01) | Parallel: 2-3 Explore agents (backend + frontend + context) |