---
name: step-05-frontend
description: Generate frontend code using MCP tools (component, API client, routes, i18n)
prev_step: steps/step-04-backend.md
next_step: steps/step-06-migration.md
---

# Step 5: Frontend Generation

## MANDATORY EXECUTION RULES

- ALWAYS use MCP tools for frontend generation
- ALWAYS generate i18n for 4 languages (fr, en, it, de)
- ALWAYS use nested routes (not flat)
- YOU ARE AN ORCHESTRATOR calling MCP, not a generator

## YOUR TASK

Use MCP tools to generate:
1. React component (scaffold_extension type: component)
2. TypeScript API client (scaffold_api_client)
3. Route configuration (scaffold_routes)
4. i18n files (scaffold_translations for UI)

---

## AVAILABLE STATE

From previous steps:

| Variable | Description |
|----------|-------------|
| `{full_path}` | Complete navigation path (navRoute) |
| `{entity_name}` | PascalCase entity name |
| `{entity_code}` | kebab-case code |
| `{labels}` | Object with fr, en, it, de |
| `{api_route}` | API endpoint path |
| `{application_kebab}` | kebab-case route segment for application (PascalCase → kebab-case, e.g., `HumanResources` → `human-resources`) |
| `{module_kebab}` | kebab-case route segment for module (PascalCase → kebab-case, e.g., `TimeManagement` → `time-management`) |

---

## ROUTE NAMING RULE

See [references/frontend-route-naming.md](../references/frontend-route-naming.md) for:
- Kebab-case transformation rules
- Forbidden patterns (concatenated words)
- Required patterns (hyphens in multi-word segments)
- Verification against navigation seed data

---

## EXECUTION SEQUENCE

### 1. Generate Frontend Pages (conventions-compliant)

```
Tool: mcp__smartstack__scaffold_extension
Args:
  type: "page"
  name: "{entity_name}"
  options:
    navRoute: "{full_path}"
    outputPath: "web/src/pages/{application}/{module}"
    dryRun: false
```

This generates (all natively compliant with /ui-components conventions):
- `{EntityName}Page.tsx` — List page wrapper with i18n
- `{EntityName}ListView.tsx` — EntityCard grid + DataTable + ViewToggle + responsive + loading/error/empty states
- `{EntityName}DetailPage.tsx` — Detail page with back button + pill tabs + info cards
- `use{EntityName}Preferences.ts` — Preferences hook (viewMode, sorting, filters, columns)
- i18n files for 4 languages (fr, en, it, de)

> **Note:** The `type: "page"` scaffold already includes CSS variables, EntityCard, responsive grid,
> semantic HTML, memo/useCallback, and all ui-components conventions. No manual corrections needed.

### 2. Generate API Client

```
Tool: mcp__smartstack__scaffold_api_client
Args:
  navRoute: "{full_path}"
  name: "{entity_name}"
  methods: ["getAll", "getById", "create", "update", "delete"]
  options:
    includeTypes: true
    includeHook: true
```

This generates:
- `services/api/{entityCode}Api.ts` - API service
- `types/{entityName}.types.ts` - TypeScript interfaces
- `hooks/use{EntityName}Api.ts` - React Query hook (optional)

### 3. Generate Route Configuration

```
Tool: mcp__smartstack__scaffold_routes
Args:
  source: "controllers"
  scope: "all"
  options:
    includeGuards: true
    generateRegistry: true
    outputFormat: "componentRegistry"
```

This generates:
- `navRoutes.generated.ts` — Route registry (NavRoute to API/web path mapping)
- `componentRegistry.generated.ts` — PageRegistry.register() calls for DynamicRouter

### 4. Verify PageRegistry Registration

After `scaffold_routes` generates the files:

1. **Verify `componentRegistry.generated.ts`** contains `PageRegistry.register()` calls
   for each new page component
2. **Verify `main.tsx`** imports `./extensions/componentRegistry.generated`
   (this should already be present — check once)
3. **Verify navigation seed data** has `ComponentKey` values matching the registered keys
   (e.g., seed Route="/administration/users" → ComponentKey="administration.users")

No manual App.tsx wiring is needed — DynamicRouter resolves routes automatically
from the API menu response + PageRegistry at runtime.

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

### 5-6. Verify i18n & Present Output

See [references/frontend-i18n-and-output.md](../references/frontend-i18n-and-output.md) for:
- i18n structure (4 language files)
- Customization of labels from feature context
- Output formatting by category (Pages, Components, API Client, Routes, i18n)

---

## ROUTING RULES

See [references/frontend-verification.md](../references/frontend-verification.md) for detailed routing rules with code examples:
- **Rule 1:** Routes MUST be inside the AppLayout wrapper
- **Rule 2:** Use NESTED routes (not flat) — flat routes bypass layout and break the shell

---

## POST-GENERATION VERIFICATION (MANDATORY)

**Before proceeding to step-06, run all 7 checks on generated frontend files.**

See [references/frontend-verification.md](../references/frontend-verification.md) for the complete checklist:
1. CSS Variables (BLOCKING) — no hardcoded Tailwind colors
2. API Client (BLOCKING) — use configured client, not raw axios
3. EntityCard — use EntityCard component for grid/card views
4. i18n (BLOCKING) — exactly 4 language files with identical keys
5. Route (BLOCKING) — inside Layout wrapper, nested, correct path convention
6. States — loading, error, empty states present
7. TypeScript Build (BLOCKING) — `npx tsc --noEmit` passes for generated files

---

## SUCCESS METRICS

- React component generated
- API client generated with types
- PageRegistry entries generated (componentRegistry.generated.ts)
- navRoutes.generated.ts updated
- Navigation seed data has matching componentKeys
- i18n files created (4 languages)
- Post-generation verification passed
- Proceeded to step-06-migration.md

## FAILURE MODES

- Component generation failed (check entity name)
- API client generation failed (check navRoute)
- Route configuration failed (check existing routes)
- Hardcoded colors detected → Fix before continuing
- Missing language files → Generate all 4 before continuing

---

## NEXT STEP

After displaying frontend code, proceed to `./step-06-migration.md`
