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