HiveGrid-Wireframes/hivegrid-cloud/docs/navigation-architecture.md

Navigation Architecture

Navigation is host-owned. Admin, tenant, public, and API links must not be mixed.

Canonical Hosts

• Admin UI uses admin-host paths through adminPath(...).
• Tenant app UI uses tenant-host paths through appPath(...) or UrlUtils.getModulePath(...) for tenant modules.
• API routes use the API host and canonical /v1/... paths through apiPath(...) where a URL helper is needed.
• Public marketing/root routes live on the root web host only when they are intentionally part of the current product surface.

Sidebar Rules

• Expandable sidebar group labels are controls, not links.
• Every clickable item needs a stable UI id, permission/flag gate when applicable, and a route that belongs to the current host.
• Admin sidebar items must never route to tenant module URLs.
• Tenant sidebar items must never point at admin host paths.

Verification

Run pnpm run verify:sidebar-routes after navigation changes. If a route, permission, or UI surface changes, update docs/ui-inventory/ and the relevant docs/feature-manifests/*.json.