design-system/README.md

# Cameleer3 Design System

A component library and interactive UI prototype for the Cameleer3 monitoring platform. This project contains both the reusable design system (primitives, composites, layout components) and a fully functional mock application demonstrating all pages and interactions.

## Prerequisites

- **Node.js** 20 or later (tested with 22.x) — [https://nodejs.org](https://nodejs.org)
- **Git** — [https://git-scm.com](https://git-scm.com)

No other tools, accounts, or access to external registries are required. All dependencies are published on the public npm registry.

## Getting Started

```bash
# 1. Clone the repository
git clone <repo-url> cameleer-design-system
cd cameleer-design-system

# 2. Install dependencies
npm install

# 3. Start the development server
npm run dev
```

The dev server will start at **http://localhost:5173** (Vite will print the exact URL).

## Available Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Start the development server with hot reload |
| `npm run build` | Type-check and build the production bundle |
| `npm run preview` | Serve the production build locally |
| `npm test` | Run the test suite (Vitest, 332 tests) |
| `npm run lint` | Run ESLint |

## Navigating the Prototype

Once the dev server is running, open **http://localhost:5173** in your browser. The application includes these sections:

### Sidebar Navigation

- **Applications** — Exchange monitoring dashboard
  - `/apps` — All exchanges across all applications
  - `/apps/:appId` — Filtered by application
  - `/apps/:appId/:routeId` — Filtered by application and route
  - Click the ↗ icon on any row to open the full **Exchange Detail** page

- **Agents** — JVM agent health monitoring
  - `/agents` — Overview of all agent instances grouped by application
  - `/agents/:appId` — Single application's agents
  - `/agents/:appId/:instanceId` — Instance detail with CPU, memory, threads, GC charts

- **Routes** — Per-route performance metrics
  - `/routes` — Aggregated KPI cards, route performance table, charts
  - `/routes/:appId` — Filtered by application
  - `/routes/:appId/:routeId` — Per-processor statistics and route flow diagram

- **Admin** — User management (RBAC), OIDC configuration, audit log
  - `/admin/rbac` — Users, groups, roles with inline editing
  - `/admin/oidc` — OIDC provider configuration form
  - `/admin/audit` — Searchable audit log table

- **Inventory** — Component showcase
  - `/inventory` — Interactive demos of every design system component

### Top Bar Controls

- **Search** (Ctrl+K) — Full-text search across applications, routes, agents, exchanges
- **Status Filters** — Toggle OK / Warn / Error / Running to filter exchanges
- **Time Range** — Preset time ranges (1h, 3h, 6h, Today, 24h, 7d) or custom date/time picker
- **Theme Toggle** (☾/☀) — Switch between light and dark mode

### Key Interactions

- **Exchange slide-in panel** — Click any row in the exchanges table to open a detail panel on the right showing overview, errors, route flow, and processor timeline
- **Exchange detail page** — Click the ↗ icon or "Open full details" link for the full inspector with Message IN/OUT panels and correlation chain
- **Processor selection** — On the exchange detail page, click any processor in the timeline or flow diagram to see its message snapshots
- **Starring** — Hover any item in the sidebar trees and click the star to pin it to the Starred section
- **Dark mode** — Click the moon/sun icon in the top bar to toggle themes

## Project Structure

```
src/
  design-system/
    primitives/     # Atomic components (Button, Input, Badge, StatusDot, ...)
    composites/     # Composed components (DataTable, Modal, EventFeed, RouteFlow, ...)
    layout/         # Page-level layout (AppShell, Sidebar, TopBar)
    providers/      # React context providers (Theme, CommandPalette, GlobalFilter)
    tokens.css      # Design tokens (colors, spacing, typography, shadows)
    utils/          # Shared utilities (hashColor, timePresets)
  pages/            # Application pages (Dashboard, Routes, AgentHealth, Admin, ...)
  mocks/            # Static mock data (exchanges, routes, agents, metrics, sidebar)
```

## Tech Stack

- **React 19** + **TypeScript**
- **Vite** for development and bundling
- **CSS Modules** for styling (all colors via design tokens)
- **Vitest** + **React Testing Library** for tests
- No runtime CSS-in-JS, no Tailwind, no external component libraries

## Notes

- All data is static mock data — no backend or API calls required
- The prototype is fully self-contained and works offline after `npm install`
- Light and dark themes are supported throughout
- Fonts (DM Sans, JetBrains Mono) are loaded from Google Fonts and require an internet connection on first load