cameleer-server/.claude/rules/ui.md

paths

paths
ui/**

UI Structure

The UI has 4 main tabs: Exchanges, Dashboard, Runtime, Deployments.

• Exchanges — route execution search and detail (ui/src/pages/Exchanges/)
• Dashboard — metrics and stats with L1/L2/L3 drill-down (ui/src/pages/DashboardTab/)
• Runtime — live agent status, logs, commands (ui/src/pages/RuntimeTab/). AgentHealth supports compact view (dense health-tinted cards) and expanded view (full GroupCard+DataTable per app). View mode persisted to localStorage.
• Deployments — app management, JAR upload, deployment lifecycle (ui/src/pages/AppsTab/)
  • Config sub-tabs: Monitoring | Resources | Variables | Traces & Taps | Route Recording
  • Create app: full page at /apps/new (not a modal)
  • Deployment progress: ui/src/components/DeploymentProgress.tsx (7-stage step indicator)

Admin pages (ADMIN-only, under /admin/):

• Sensitive Keys (ui/src/pages/Admin/SensitiveKeysPage.tsx) — global sensitive key masking config. Shows agent built-in defaults as outlined Badge reference, editable Tag pills for custom keys, amber-highlighted push-to-agents toggle. Keys add to (not replace) agent defaults. Per-app sensitive key additions managed via ApplicationConfigController API. Note: AppConfigDetailPage.tsx exists but is not routed in router.tsx.

Key UI Files

• ui/src/router.tsx — React Router v6 routes
• ui/src/config.ts — apiBaseUrl, basePath
• ui/src/auth/auth-store.ts — Zustand: accessToken, user, roles, login/logout
• ui/src/api/environment-store.ts — Zustand: selected environment (localStorage)
• ui/src/components/ContentTabs.tsx — main tab switcher
• ui/src/components/ExecutionDiagram/ — interactive trace view (canvas)
• ui/src/components/ProcessDiagram/ — ELK-rendered route diagram
• ui/src/hooks/useScope.ts — TabKey type, scope inference
• ui/src/components/StartupLogPanel.tsx — deployment startup log viewer (container logs from ClickHouse, polls 3s while STARTING)
• ui/src/api/queries/logs.ts — useStartupLogs hook for container startup log polling, useLogs/useApplicationLogs for general log search

UI Styling

• Always use @cameleer/design-system CSS variables for colors (var(--amber), var(--error), var(--success), etc.) — never hardcode hex values. This applies to CSS modules, inline styles, and SVG fill/stroke attributes. SVG presentation attributes resolve var() correctly. All colors use CSS variables (no hardcoded hex).
• Shared CSS modules in ui/src/styles/ (table-section, log-panel, rate-colors, refresh-indicator, chart-card, section-card) — import these instead of duplicating patterns.
• Shared PageLoader component replaces copy-pasted spinner patterns.
• Design system components used consistently: Select, Tabs, Toggle, Button, LogViewer, Label — prefer DS components over raw HTML elements. LogViewer renders optional source badges (container, app, agent) via LogEntry.source field (DS v0.1.49+).
• Environment slugs are auto-computed from display name (read-only in UI).
• Brand assets: @cameleer/design-system/assets/ provides camel-logo.svg (currentColor), cameleer-{16,32,48,192,512}.png, and cameleer-logo.png. Copied to ui/public/ for use as favicon (favicon-16.png, favicon-32.png) and logo (camel-logo.svg — login dialog 36px, sidebar 28x24px).
• Sidebar generates /exchanges/ paths directly (no legacy /apps/ redirects). basePath is centralized in ui/src/config.ts; router.tsx imports it instead of re-reading <base> tag.
• Global user preferences (environment selection) use Zustand stores with localStorage persistence — never URL search params. URL params are for page-specific state only (e.g. ?text= search query). Switching environment resets all filters and remounts pages.