---
name: step-03-navigation
description: Define the complete navigation tree (routes, menus, breadcrumbs)
model: opus
---

# Step 03 — Navigation (Navigation Tree)

## Objective

Define the complete navigation tree for the project: routes, menus, breadcrumbs per application. Supports multi-app projects (uses `applications[]` array).

## Prerequisites

- Step 01 (screens) and Step 02 (wireframes) completed
- screens.json exists for each module with sections and resources

## Execution

### 1. Load All Screens

Read screens.json for every module via ba-reader. Collect all sections and resources.

### 2. Build Navigation Tree

Build the navigation hierarchy following SmartStack conventions:

> **Route depth:** Max 3 segments: `/{app-code}/{module-code}/{section-code}`.
> Use `:id` for detail sections (e.g., `/rh/employees/:id`).
> Resources are components WITHIN a page, NOT separate routes.

```
Project
  |-- Application 1 (e.g., HumanResources)
  |   |-- Module 1 (e.g., Employees)
  |   |   |-- Section "list"   → /rh/employees       (isDefault, showInMenu)
  |   |   |-- Section "detail" → /rh/employees/:id   (showInMenu: false)
  |   |   |-- Section "dashboard" → /rh/employees/dashboard (showInMenu)
  |   |-- Module 2 (e.g., Absences)
  |-- Application 2 (e.g., Billing)
      |-- ...
```

### 3. Generate navigation.json

> **Multi-app format is MANDATORY.** Even for single-app projects, use `applications[]` (array of 1).

```json
{
  "applications": [
    {
      "code": "{AppCode}",
      "name": "{AppName}",
      "icon": "app-icon",
      "route": "/{app-code}",
      "modules": [
        {
          "code": "{ModuleCode}",
          "name": "{ModuleName}",
          "icon": "module-icon",
          "route": "/{app-code}/{module-code}",
          "permission": "{AppCode}.{ModuleCode}.Read",
          "sections": [
            {
              "code": "{sectionCode}",
              "label": "{sectionLabel}",
              "route": "/{app-code}/{module-code}/{section-code}",
              "icon": "section-icon",
              "isDefault": false,
              "showInMenu": true,
              "resources": [
                {
                  "code": "{resourceCode}",
                  "type": "{SmartTable|SmartForm|SmartDashboard|SmartKanban|SmartFilter}",
                  "permission": "{AppCode}.{ModuleCode}.{Action}"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "menuItems": [
    {
      "label": "{AppName}",
      "icon": "app-icon",
      "route": "/{app-code}",
      "children": [
        {
          "label": "{ModuleName}",
          "icon": "module-icon",
          "route": "/{app-code}/{module-code}",
          "permission": "{AppCode}.{ModuleCode}.Read",
          "children": [
            {
              "label": "{sectionLabel}",
              "route": "/{app-code}/{module-code}/{section-code}",
              "permission": "{AppCode}.{ModuleCode}.Read"
            }
          ]
        }
      ]
    }
  ],
  "breadcrumbs": {
    "/{app-code}/{module-code}/{section-code}": [
      { "label": "{AppName}", "route": "/{app-code}" },
      { "label": "{ModuleName}", "route": "/{app-code}/{module-code}" },
      { "label": "{sectionLabel}", "route": "" }
    ]
  }
}
```

**Section properties:**

| Property | Type | Description |
|----------|------|-------------|
| `isDefault` | boolean | Default section for the module (typically `list`). Only ONE per module. |
| `showInMenu` | boolean | `true` = visible in sidebar menu, `false` = accessible by navigation only (e.g., detail pages) |

**menuItems rules:**

| Rule | Description |
|------|-------------|
| App-level items have NO `permission` | Applications are visible to all authenticated users; permissions gate modules/sections |
| Single visible section = no `children` | If a module has only ONE section with `showInMenu: true`, render a direct link (no submenu) |
| Only `showInMenu: true` sections | Detail sections (`showInMenu: false`) are NOT included in menuItems |

**Route conventions:**

| Level | Format | Example |
|-------|--------|---------|
| Application | `/{app-code}` | `/rh` |
| Module | `/{app-code}/{module-code}` | `/rh/employees` |
| Section (list/default) | `/{app-code}/{module-code}` | `/rh/employees` (isDefault) |
| Section (named) | `/{app-code}/{module-code}/{section-code}` | `/rh/employees/dashboard` |
| Section (detail) | `/{app-code}/{module-code}/:id` | `/rh/employees/:id` |

> **Max 3 segments.** Resources are components within a page, NOT separate routes.

### 4. Write navigation.json

Write via ba-writer at project level: `{docs_dir}/navigation.json` (e.g., `docs/projet-rh/v1.0/navigation.json`).
Update index.json with navigation.json reference.

## Validation

- [ ] Every module in index.json has a corresponding navigation entry
- [ ] Every section with `showInMenu: true` has a corresponding menu item
- [ ] Every route is unique (no duplicates across all applications)
- [ ] Module/section-level menu items have valid permission references
- [ ] App-level menu items have NO permission (visible to all)
- [ ] Breadcrumbs cover ALL routes (every route in `applications[].modules[].sections[]` must have a breadcrumb entry)
- [ ] `isDefault: true` is set on exactly ONE section per module
- [ ] Routes use max 3 segments (+ `:id` for detail)
- [ ] Single-section modules have no `children` in menuItems

## Completion Summary

```
================================================================
  UI DESIGN COMPLETE
================================================================

| Module          | Sections | Resources | Wireframes |
|-----------------|----------|-----------|------------|
| {moduleCode}    | {count}  | {count}   | {count}    |
| ...             | ...      | ...       | ...        |

| Artifact        | Path                              |
|-----------------|-----------------------------------|
| screens.json    | {docs_dir}/{app-kebab}/{module-kebab}/screens.json |
| navigation.json | {docs_dir}/navigation.json                        |

NEXT STEPS:
1. Run /business-analyse-html to produce the interactive HTML with mockups
2. Client reviews the HTML (mockups, ERD, permission matrix)
3. Run /business-analyse-review to apply corrections
================================================================
```

## Status Update

After writing all screens and navigation, update the application status:
```javascript
ba-writer.updateStatus({feature_id}, "designed")
```
