cameleer-server/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Cameleer3 Server — observability server that receives, stores, and serves Camel route execution data and route diagrams from Cameleer3 agents. Pushes config and commands to agents via SSE.

Related Project

• cameleer3 (https://gitea.siegeln.net/cameleer/cameleer3) — the Java agent that instruments Camel applications
• Protocol defined in cameleer3-common/PROTOCOL.md in the agent repo
• This server depends on com.cameleer3:cameleer3-common (shared models and graph API)

Modules

• cameleer3-server-core — domain logic, storage, agent registry
• cameleer3-server-app — Spring Boot web app, REST controllers, SSE, static resources

Build Commands

mvn clean compile          # Compile all modules
mvn clean verify           # Full build with tests

Run

java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar

Key Conventions

• Java 17+ required
• Spring Boot 3.4.3 parent POM
• Depends on com.cameleer3:cameleer3-common from Gitea Maven registry
• Jackson JavaTimeModule for Instant deserialization
• Communication: receives HTTP POST data from agents, serves SSE event streams for config push/commands
• Maintains agent instance registry with states: LIVE → STALE → DEAD
• Storage: ClickHouse for structured data, text index for full-text search
• Security: JWT auth, Ed25519 config signing, bootstrap token for registration

CI/CD & Deployment

• CI workflow: .gitea/workflows/ci.yml — build → docker → deploy on push to main
• Build step skips integration tests (-DskipITs) — Testcontainers needs Docker daemon
• Docker: multi-stage build (Dockerfile), $BUILDPLATFORM for native Maven on ARM64 runner, amd64 runtime
• REGISTRY_TOKEN build arg required for cameleer3-common dependency resolution
• Registry: gitea.siegeln.net/cameleer/cameleer3-server (container images)
• K8s manifests in deploy/ — ClickHouse StatefulSet + server Deployment + NodePort Service (30081)
• Deployment target: k3s at 192.168.50.86, namespace cameleer
• Secrets managed in CI deploy step (idempotent --dry-run=client | kubectl apply)
• Docker build uses buildx registry cache + --provenance=false for Gitea compatibility