From 726e77bb91ccbd9836ec6d54527dcfb2ab1b6bb6 Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Fri, 3 Apr 2026 11:22:44 +0200 Subject: [PATCH] docs: update all documentation for session changes CLAUDE.md: - Agent registry auto-heal note (in-memory, JWT fallback) - Usage analytics (ClickHouse usage_events table) HOWTO.md: - Architecture diagram: added deploy-demo (NodePort 30092) and cameleer-demo namespace - Access URLs: added Deploy Demo - Agent registry: server restart resilience documentation - Route control: CommandGroupResponse note ui/README.md: - Fixed outdated generate-api command - Added DS version (v0.1.26) - Fixed VITE_API_TARGET (30081 not 30090) - Added key features section (cmd-k, LIVE mode, route control, event icons) Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 3 ++- HOWTO.md | 9 +++++++++ ui/README.md | 14 +++++++++++--- 3 files changed, 22 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c17d8e9a..68086069 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,11 +37,12 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar - Depends on `com.cameleer3:cameleer3-common` from Gitea Maven registry - Jackson `JavaTimeModule` for `Instant` deserialization - Communication: receives HTTP POST data from agents (executions, diagrams, metrics, logs), serves SSE event streams for config push/commands (config-update, deep-trace, replay, route-control) -- Maintains agent instance registry with states: LIVE → STALE → DEAD +- Maintains agent instance registry (in-memory) with states: LIVE → STALE → DEAD. Auto-heals from JWT claims on heartbeat/SSE after server restart. Route catalog falls back to ClickHouse stats for route discovery when registry has incomplete data. - Storage: PostgreSQL for RBAC, config, and audit; ClickHouse for all observability data (executions, search, logs, metrics, stats, diagrams) - Security: JWT auth with RBAC (AGENT/VIEWER/OPERATOR/ADMIN roles), Ed25519 config signing, bootstrap token for registration - OIDC: Optional external identity provider support (token exchange pattern). Configured via admin API, stored in database (`server_config` table) - User persistence: PostgreSQL `users` table, admin CRUD at `/api/v1/admin/users` +- Usage analytics: ClickHouse `usage_events` table tracks authenticated UI requests, flushed every 5s ## CI/CD & Deployment diff --git a/HOWTO.md b/HOWTO.md index 22b5d18e..e6eab38f 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -343,10 +343,14 @@ curl -s -X POST http://localhost:8081/api/v1/agents/agent-1/commands/{commandId} **Agent lifecycle:** LIVE (heartbeat within 90s) → STALE (missed 3 heartbeats) → DEAD (5min after STALE). DEAD agents kept indefinitely. +**Server restart resilience:** The agent registry is in-memory and lost on server restart. Agents auto-re-register on their next heartbeat or SSE connection — the server reconstructs registry entries from JWT claims (subject, application). Route catalog uses ClickHouse execution data as fallback until agents re-register with full route IDs. Agents should also handle 404 on heartbeat by triggering a full re-registration. + **SSE events:** `config-update`, `deep-trace`, `replay`, `route-control` commands pushed in real time. Server sends ping keepalive every 15s. **Command expiry:** Unacknowledged commands expire after 60 seconds. +**Route control responses:** Route control commands return `CommandGroupResponse` with per-agent status, response count, and timed-out agent IDs. + ### Backpressure When the write buffer is full (default capacity: 50,000), ingestion endpoints return **503 Service Unavailable**. Already-buffered data is not lost. @@ -440,10 +444,14 @@ cameleer namespace: ClickHouse (StatefulSet, 10Gi PVC) ← clickhouse:8123 (ClusterIP) cameleer3-server (Deployment) ← NodePort 30081 cameleer3-ui (Deployment, Nginx) ← NodePort 30090 + cameleer-deploy-demo (Deployment) ← NodePort 30092 Authentik Server (Deployment) ← NodePort 30950 Authentik Worker (Deployment) Authentik PostgreSQL (StatefulSet, 1Gi) ← ClusterIP Authentik Redis (Deployment) ← ClusterIP + +cameleer-demo namespace: + (deployed Camel applications — managed by cameleer-deploy-demo) ``` ### Access (from your network) @@ -453,6 +461,7 @@ cameleer namespace: | Web UI | `http://192.168.50.86:30090` | | Server API | `http://192.168.50.86:30081/api/v1/health` | | Swagger UI | `http://192.168.50.86:30081/api/v1/swagger-ui.html` | +| Deploy Demo | `http://192.168.50.86:30092` | | Authentik | `http://192.168.50.86:30950` | ### CI/CD Pipeline diff --git a/ui/README.md b/ui/README.md index d77bfe77..e0de5b44 100644 --- a/ui/README.md +++ b/ui/README.md @@ -1,6 +1,6 @@ # Cameleer3 UI -React SPA built with [@cameleer/design-system](https://gitea.siegeln.net/cameleer/design-system), TanStack Query, and Zustand. +React SPA built with [@cameleer/design-system](https://gitea.siegeln.net/cameleer/design-system) v0.1.26, TanStack Query, and Zustand. ## Development @@ -12,7 +12,7 @@ npm run dev By default the dev server proxies `/api/*` to `http://localhost:8081`. To proxy to a remote server instead: ```bash -VITE_API_TARGET=http://192.168.50.86:30090 npm run dev +VITE_API_TARGET=http://192.168.50.86:30081 npm run dev ``` No CORS issues — Vite's proxy makes API calls server-side. @@ -28,5 +28,13 @@ npm run build Regenerate TypeScript types from a running backend: ```bash -npm run generate-api:live +npm run generate-api # Requires backend running on :8081 ``` + +## Key Features + +- **Composable sidebar** with accordion behavior (Applications / Starred / Admin sections) +- **Context-aware cmd-k search**: shows apps/routes/exchanges on operational pages, users/groups/roles on admin pages +- **LIVE mode toggle**: when ON, queries poll at intervals (5s-30s); when OFF, sidebar clicks trigger manual refresh +- **Route control bar** with state-aware buttons (start/stop/suspend/resume) and confirmation dialogs +- **Event-type icons** in agent timeline with severity-based coloring