# Navigation Metadata

This page details the navigation metadata tables that drive the Calminer sidebar and top-level menus. It was split from `02_data_model.md` to isolate runtime navigation behaviour from the broader ORM catalogue.

## NavigationGroup

Represents a logical grouping of navigation links shown in the UI sidebar or header.

**Table:** `navigation_groups`

| Attribute    | Type         | Description                                     |
| ------------ | ------------ | ----------------------------------------------- |
| id           | Integer (PK) | Primary key                                     |
| slug         | String(64)   | Unique slug identifier                          |
| title        | String(128)  | Display title                                   |
| description  | Text         | Optional descriptive text                       |
| match_prefix | String(255)  | URL prefix used to auto-expand in UI            |
| weighting    | Integer      | Ordering weight                                 |
| icon_name    | String(64)   | Optional icon identifier                        |
| feature_flag | String(64)   | Optional feature flag for conditional rendering |
| created_at   | DateTime     | Creation timestamp                              |
| updated_at   | DateTime     | Last update timestamp                           |

**Relationships:**

- `links`: One-to-many with NavigationLink

## NavigationLink

Individual navigation entry that may have an associated feature flag or role restriction.

**Table:** `navigation_links`

| Attribute     | Type                                | Description                                          |
| ------------- | ----------------------------------- | ---------------------------------------------------- |
| id            | Integer (PK)                        | Primary key                                          |
| group_id      | Integer (FK → navigation_groups.id) | Parent navigation group                              |
| parent_id     | Integer (FK → navigation_links.id)  | Optional parent link (for nested menus)              |
| slug          | String(64)                          | Unique slug identifier                               |
| title         | String(128)                         | Display title                                        |
| description   | Text                                | Optional descriptive text                            |
| href          | String(255)                         | Static fallback URL                                  |
| match_prefix  | String(255)                         | URL prefix for expansion                             |
| feature_flag  | String(64)                          | Optional feature flag for conditional rendering      |
| required_role | String(64)                          | Optional role required to view the link              |
| weighting     | Integer                             | Ordering weight within the parent scope              |
| icon_name     | String(64)                          | Optional icon identifier                             |
| metadata      | JSON                                | Additional configuration (e.g. legacy route aliases) |
| created_at    | DateTime                            | Creation timestamp                                   |
| updated_at    | DateTime                            | Last update timestamp                                |

**Relationships:**

- `group`: Many-to-one with NavigationGroup
- `parent`: Many-to-one self-reference
- `children`: One-to-many self-reference

## Seeding and Runtime Consumption

- **Seed script:** `scripts/init_db.py` provisions baseline groups and links, including nested scenario calculators and role-gated admin entries.
- **Service layer:** `services/navigation.py` maps ORM entities into response DTOs, resolves contextual URLs for projects and scenarios, and applies feature flag as well as role filters.
- **API exposure:** `routes/navigation.py` serves the `/navigation/sidebar` endpoint, combining seeded data with runtime context to produce navigation trees consumed by the frontend.
- **Testing:** `tests/services/test_navigation_service.py` covers URL resolution and child filtering logic, while `tests/integration/test_navigation_sidebar_calculations.py` verifies scenario calculator entries in the API payload.

Refer to the [navigation service documentation](../../../../api/README.md#navigation) for endpoint-level behaviour.