cameleer-server/docs/superpowers/specs/2026-03-28-navigation-redesign-design.md

Navigation Redesign: Persona-Driven Layout

Status: Implemented (2026-03-28)

Context

The Cameleer UI was redesigned from page-based routing to a scope-based model with three content tabs. The Process Diagram is the major USP for the Apache Camel community.

Core Model

Sidebar scopes WHERE (app -> route hierarchy), content tabs switch WHAT (Exchanges | Dashboard | Runtime).

Layout Shell

┌──────────────────────────────────────────────────────────────────────────────┐
│ TopBar: [All > order-svc > route-a]  [Cmd+K]  [filters]  [user]           │
├───────────┬──────────────────────────────────────────────────────────────────┤
│ Sidebar   │ [ Exchanges | Dashboard | Runtime ]   TOTAL 443↑ ERR% 0.0%↓  │
│           ├──────────────────────────────────────────────────────────────────┤
│ Apps      │                                                                │
│ ● app-1   │ Content area (layout varies by tab + selection)               │
│ ◐ app-2   │                                                                │
│ ▾ app-3   │                                                                │
│   route-a │                                                                │
│   route-b │                                                                │
│           │                                                                │
│ ⚙ Admin   │                                                                │
└───────────┴──────────────────────────────────────────────────────────────────┘

Sidebar

Simplified to app -> route hierarchy only. No agents (accessible via Runtime tab). Sidebar clicks act as scope filters via event interception (display: contents wrapper intercepts Link clicks and re-routes through current tab).

Scope Trail

Integrated into the TopBar breadcrumb (not a separate component). Shows: All Applications > appId > routeId.

Tab Bar with Inline KPIs

Content tabs (Exchanges | Dashboard | Runtime) rendered using design system Tabs component. Right-aligned compact KPI metrics show: Total, Err%, Avg, P99 — each with trend arrow (green=good, red=bad) computed from useExecutionStats. KPIs are scope-aware.

Tab: Exchanges (Primary USP)

Full-width mode (no exchange selected)

Exchange table (DataTable from design system) with search, sort, filter. No KPI strip (metrics are in the tab bar). Clicking a row selects the exchange via local state (not URL navigation — preserves search scope).

Split mode (exchange selected)

Draggable 50:50 split (20%-80% range, amber highlight on drag):

┌──────────────────────┬───────────────────────────────────────┐
│ Exchange Table       │ Exchange Header                       │
│ (same DataTable,     │  status | attrs | app route | agent   │
│  search preserved)   │ Correlated Exchanges (chain)          │
│                      ├───────────────────────────────────────┤
│                      │ Process Diagram (execution overlay)   │
│                      │  + minimap (bottom-right, above zoom) │
│                      ├───────────────────────────────────────┤
│                      │ Detail Panel (tabs)                   │
│                      │  Info|Headers|Input|Output|Error|     │
│                      │  Config|Timeline|Log                  │
└──────────────────────┴───────────────────────────────────────┘

Exchange Header features:

• Status dot + badge + tap-collected attribute badges (consistent color via value hash)
• Clickable app name (resets to app scope), route name + GitBranch icon (resets to route scope)
• Clickable agent name + ID + Server icon (colored by agent state: green/yellow/red) -> agent pages
• Correlation chain with StatusDot per node, route name + duration, arrow connectors, total duration (far right)
• Clicking a correlated exchange switches the diagram via local state
• Clicking app/route clears the selection (returns to full-width table)

Browser history integration:

• Each exchange selection pushes a history entry with the selection in location.state
• Back/Forward restores the exact selection state (split view reappears)
• Navigating to agent details and pressing Back returns to the diagram

Detail Panel tabs: Info, Headers (sorted alphabetically), Input, Output, Error, Config, Timeline, Log (new — shows exchange logs filtered by processor when selected).

Tab: Dashboard

Wraps existing pages: RoutesMetrics (no route scope) or RouteDetail (route scoped).

Tab: Runtime

Wraps existing pages: AgentHealth (no agent scope) or AgentInstance (agent selected).

Admin

Gear icon in sidebar footer. Unchanged tab-based layout (RBAC, Audit, OIDC, AppConfig, DB, OpenSearch).

URL Structure

/exchanges                    -> Exchanges tab, no scope
/exchanges/:appId             -> Exchanges tab, app-scoped
/exchanges/:appId/:routeId    -> Exchanges tab, route-scoped
/dashboard                    -> Dashboard tab
/dashboard/:appId             -> Dashboard tab, app-scoped
/dashboard/:appId/:routeId    -> Dashboard tab, route-scoped
/runtime                      -> Runtime tab
/runtime/:appId               -> Runtime tab, app-scoped
/runtime/:appId/:instanceId   -> Runtime tab, agent detail
/admin/*                      -> Admin (unchanged)
/apps/*, /agents/*            -> Legacy redirects to new paths

Default / redirects to /exchanges.

Key Implementation Files

File	Purpose
ui/src/hooks/useScope.ts	URL scope parsing + navigation helpers
ui/src/components/ContentTabs.tsx	Tab bar with inline KPIs
ui/src/components/TabKpis.tsx	Compact KPI metrics (Total, Err%, Avg, P99)
ui/src/components/LayoutShell.tsx	Shell with sidebar interception, scope trail, tabs
ui/src/pages/Exchanges/ExchangesPage.tsx	Full-width / split orchestrator with history state
ui/src/pages/Exchanges/ExchangeHeader.tsx	Exchange info bar + correlation chain
ui/src/pages/Dashboard/Dashboard.tsx	Exchange table (accepts onExchangeSelect callback)
ui/src/pages/RuntimeTab/RuntimePage.tsx	AgentHealth / AgentInstance wrapper
ui/src/pages/DashboardTab/DashboardPage.tsx	RoutesMetrics / RouteDetail wrapper
ui/src/utils/attribute-color.ts	Deterministic badge color from value hash
ui/src/components/ExecutionDiagram/tabs/LogTab.tsx	Log tab for detail panel
ui/src/router.tsx	Tab-based routes + legacy redirects

What Differentiates from njams

1. Three-tab model — njams interleaves everything; Cameleer separates concerns
2. Inline KPI metrics — compact stats in the tab bar with trend indicators
3. State-based selection — exchange selection via local state, not URL navigation (preserves search)
4. Browser history integration — Back/Forward restores exchange selection
5. Scope-based sidebar — filters rather than navigates
6. Runtime tab — dedicated agent monitoring
7. Draggable split — resizable divider between table and diagram
8. Correlation chain — arrow-connected nodes with route names, durations, total duration
9. Attribute badges — consistent colors across all views via value hash