# 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 BusinessLayout (shell renders: header + AvatarMenu + sidebar)
<Route path="/business" element={<BusinessLayout />}>
  <Route path="sales/products" element={<ProductsPage />} />
</Route>

// FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
<Route path="/business/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="/business" element={<BusinessLayout />}>
  <Route path="sales">
    <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="/business/sales" element={<Navigate to="products" />} />
<Route path="/business/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:
- **INSIDE** the Layout wrapper (`BusinessLayout`, `AdminLayout`, or `UserLayout`)
- **NESTED** (not flat)
- Following path convention: `/{context}/{application_kebab}/{module_kebab}` (kebab-case)

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

Verify routes are actually wired into App.tsx (not just generated in standalone files):

1. Open `App.tsx` (or `main.tsx`)
2. Verify the new route path appears **inside** the correct Layout wrapper
3. Verify the route also appears inside the **tenant-prefixed** block (`/t/:slug/...`)
4. Verify the page component is imported (lazy-loaded) at the top of the file

**If routes are only in `clientRoutes.generated.tsx` or `routes/index.tsx` but NOT in App.tsx, the routes will NOT work at runtime — page will be BLANK.**

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

If `appWiring.issues` is not empty, fix the wiring 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 path strings from App.tsx (both `contextRoutes` and `<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/{context}/{application}/{module}/*.tsx`
- `services/api/{entityCode}Api.ts`
- `types/{entityName}.types.ts`
- `hooks/use{EntityName}*.ts`
