# Frontend: Routing Rules & Post-Generation Verification

> Reference for step-05-frontend.md — routing rules and mandatory verification checks.

## Routing Rules

### Rule 1: Routes MUST be inside Layout wrappers

**CRITICAL:** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation).

```tsx
// CORRECT - Inside SalesLayout (shell renders: header + AvatarMenu + sidebar)
<Route path="/sales" element={<SalesLayout />}>
  <Route path="products" element={<ProductsPage />} />
</Route>

// FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
<Route path="/sales/products" element={<ProductsPage />} />
```

### Rule 2: Use nested routes (not flat)

**CRITICAL:** SmartStack requires NESTED routes within the layout:

```tsx
// CORRECT - Nested routes inside layout
<Route path="/sales" element={<SalesLayout />}>
  <Route path="products">
    <Route index element={<Navigate to="products" replace />} />
    <Route path="products" element={<ProductsPage />} />
    <Route path="orders" element={<OrdersPage />} />
  </Route>
</Route>

// FORBIDDEN - Flat routes (cause redirect issues + bypass layout)
<Route path="/sales/products" element={<Navigate to="products" />} />
<Route path="/sales/products" element={<ProductsPage />} />
```

## Post-Generation Verification (MANDATORY)

**Before proceeding to step-06, run these checks on ALL generated frontend files:**

### 1. CSS Variables Check (BLOCKING)

Scan all generated `.tsx` files for hardcoded Tailwind colors:

```
FORBIDDEN patterns: bg-blue-, bg-red-, bg-green-, bg-gray-, bg-amber-,
                    text-blue-, text-red-, text-green-, text-gray-, text-amber-,
                    border-blue-, border-red-, border-green-, border-gray-
```

If ANY hardcoded color is found → **FIX IT** using CSS variables from style-guide.md before continuing.

### 2. API Client Check (BLOCKING)

Verify all API service files use the configured client:
- **CORRECT:** `import { api } from '@/services/api/apiClient'` or `import api from '../api'`
- **FORBIDDEN:** `import axios from 'axios'`

### 3. EntityCard Check

If a grid/card view is generated, verify it uses `EntityCard` component (not custom divs).

### 4. i18n Check (BLOCKING)

Verify exactly **4 language files** exist with identical key structures:
- `fr/{entityCode}.json`
- `en/{entityCode}.json`
- `it/{entityCode}.json`
- `de/{entityCode}.json`

### 5. Route Check (BLOCKING)

Verify routes are registered:
- **v3.7+ (DynamicRouter):** PageRegistry.register() exists in componentRegistry.generated.ts
- **Legacy:** inside Layout wrapper, nested, correct path convention
- Following path convention: `/{application_kebab}/{module_kebab}` (kebab-case)

### 5b. Route Wiring Check (BLOCKING)

**v3.7+ (DynamicRouter):** Verify PageRegistry registration:

1. Open `componentRegistry.generated.ts`
2. Verify new pages have `PageRegistry.register()` calls with matching componentKeys
3. Verify `main.tsx` imports `./extensions/componentRegistry.generated`
4. DynamicRouter resolves routes automatically — no App.tsx wiring needed

**Legacy:** Verify routes are wired into App.tsx (inside Layout wrapper + tenant block).

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

If validation returns issues, fix before proceeding.

### 5c. Route Kebab-Case Check (BLOCKING)

Scan App.tsx route paths for non-kebab-case segments:

**FORBIDDEN** — concatenated multi-word segments without hyphens:
- `humanresources`, `timemanagement`, `mymodule` (when representing multi-word names)

**REQUIRED** — proper kebab-case for multi-word segments:
- `human-resources`, `time-management`

**Verification steps:**

1. Extract all route keys from `componentRegistry.generated.ts` (v3.7+) or App.tsx (`applicationRoutes` / `<Route path="...">`)
2. For each multi-word path segment, verify it uses hyphens (kebab-case)
3. Cross-reference route paths with navigation seed data routes to ensure exact match
4. Single-word segments are fine as-is (e.g., `employees`, `products`)

**Grep check** — verify no multi-word segments without hyphens in route paths:
```bash
# Should return NO matches for multi-word segments without hyphens
grep -E "path:\s*['\"]([a-z]+[A-Z]|[a-z]{2,}[a-z]{2,}/)" App.tsx
```

If ANY non-kebab-case multi-word route segment is found → **FIX IT** before continuing.

### 6. States Check

Verify the list page includes:
- Loading state (spinner)
- Error state (icon + message + retry button)
- Empty state (icon + message)

### 7. TypeScript Build Check (BLOCKING)

Run the frontend type check to verify all generated files compile:

```bash
cd web && npx tsc --noEmit 2>&1 | head -50
```

OR if the project uses a build script:

```bash
cd web && npm run build 2>&1 | head -80
```

IF type errors exist **in generated files**: Fix them before proceeding.
Common issues: missing imports, wrong interface names, incorrect prop types, missing hook return types.

IF type errors exist **in other pre-existing files**: NON-BLOCKING. Note them but proceed.

**Focus only on errors in files generated by this step:**
- `pages/{application}/{module}/*.tsx`
- `services/api/{entityCode}Api.ts`
- `types/{entityName}.types.ts`
- `hooks/use{EntityName}*.ts`
