CLAUDE.md

# CLAUDE.md

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

## Project

Cameleer SaaS — multi-tenant SaaS platform wrapping the Cameleer observability stack (Java agent + server) for Apache Camel applications. Customers get managed observability for their Camel integrations without running infrastructure.

## Ecosystem

This repo is the SaaS layer on top of two proven components:

- **cameleer3** (sibling repo) — Java agent using ByteBuddy for zero-code instrumentation of Camel apps. Captures route executions, processor traces, payloads, metrics, and route graph topology. Deploys as `-javaagent` JAR.
- **cameleer3-server** (sibling repo) — Spring Boot observability backend. Receives agent data via HTTP, pushes config/commands via SSE. PostgreSQL + OpenSearch storage. React SPA dashboard. JWT auth with Ed25519 config signing.
- **cameleer-website** — Marketing site (Astro 5)
- **design-system** — Shared React component library (`@cameleer/design-system` on Gitea npm registry)

Agent-server protocol is defined in `cameleer3/cameleer3-common/PROTOCOL.md`. The agent and server are mature, proven components — this repo wraps them with multi-tenancy, billing, and self-service onboarding.

## Architecture Context

The existing cameleer3-server already has single-tenant auth (JWT, RBAC, bootstrap tokens, OIDC). The SaaS layer must:
- Add multi-tenancy (tenant isolation of agent data, diagrams, configs)
- Provide self-service signup, billing, and team management
- Generate per-tenant bootstrap tokens for agent registration
- Proxy or federate access to tenant-specific cameleer3-server instances
- Enforce usage quotas and metered billing

Auth enforcement (current state):
- All API endpoints enforce OAuth2 scopes via `@PreAuthorize("hasAuthority('SCOPE_xxx')")` annotations
- Tenant isolation enforced at two levels: `TenantResolutionFilter` (rejects cross-tenant path access) and `TenantOwnershipValidator` (verifies resource ownership at service level)
- 10 OAuth2 scopes defined on the Logto API resource (`https://api.cameleer.local`), served to the frontend from `GET /api/config`

## Related Conventions

- Gitea-hosted: `gitea.siegeln.net/cameleer/`
- CI: `.gitea/workflows/` — Gitea Actions
- K8s target: k3s cluster at 192.168.50.86
- Docker builds: multi-stage, buildx with registry cache, `--provenance=false` for Gitea compatibility
- Design system: import from `@cameleer/design-system` (Gitea npm registry)

## Disabled Skills

- Do NOT use any `gsd:*` skills in this project. This includes all `/gsd:` prefixed commands.
Add moat-strengthening features design spec Comprehensive design document for three defensibility features: - Live Route Debugger (replay-based, zero production impact) - Payload Flow Lineage (targeted per-processor capture + diff) - Cross-Service Trace Correlation + Topology Map (network effect) Gitea issues: cameleer/cameleer3 #57-#72 (MOAT label) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> 2026-03-29 16:14:04 +02:00			`# CLAUDE.md`

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

			`## Project`

			`Cameleer SaaS — multi-tenant SaaS platform wrapping the Cameleer observability stack (Java agent + server) for Apache Camel applications. Customers get managed observability for their Camel integrations without running infrastructure.`

			`## Ecosystem`

			`This repo is the SaaS layer on top of two proven components:`

			- cameleer3 (sibling repo) — Java agent using ByteBuddy for zero-code instrumentation of Camel apps. Captures route executions, processor traces, payloads, metrics, and route graph topology. Deploys as `-javaagent` JAR.
			`- cameleer3-server (sibling repo) — Spring Boot observability backend. Receives agent data via HTTP, pushes config/commands via SSE. PostgreSQL + OpenSearch storage. React SPA dashboard. JWT auth with Ed25519 config signing.`
			`- cameleer-website — Marketing site (Astro 5)`
			- design-system — Shared React component library (`@cameleer/design-system` on Gitea npm registry)

			Agent-server protocol is defined in `cameleer3/cameleer3-common/PROTOCOL.md`. The agent and server are mature, proven components — this repo wraps them with multi-tenancy, billing, and self-service onboarding.

			`## Architecture Context`

			`The existing cameleer3-server already has single-tenant auth (JWT, RBAC, bootstrap tokens, OIDC). The SaaS layer must:`
			`- Add multi-tenancy (tenant isolation of agent data, diagrams, configs)`
			`- Provide self-service signup, billing, and team management`
			`- Generate per-tenant bootstrap tokens for agent registration`
			`- Proxy or federate access to tenant-specific cameleer3-server instances`
			`- Enforce usage quotas and metered billing`

feat: auth hardening — scope enforcement, tenant isolation, and docs Add @PreAuthorize annotations to all API controllers (14 endpoints across 6 controllers) enforcing OAuth2 scopes: apps:manage, apps:deploy, billing:manage, observe:read, platform:admin. Enforce tenant isolation: TenantResolutionFilter now rejects cross-tenant access on /api/tenants/{id}/* paths. New TenantOwnershipValidator checks environment/app ownership for paths without tenantId. Platform admins bypass both layers. Fix frontend: OrgResolver split into two useEffect hooks so scopes refresh on org switch. Scopes now served from /api/config (single source of truth). Bootstrap cleaned — standalone org permissions removed. Update docs/architecture.md, docs/user-manual.md, and CLAUDE.md to reflect all auth hardening changes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> 2026-04-05 15:32:53 +02:00			`Auth enforcement (current state):`
			- All API endpoints enforce OAuth2 scopes via `@PreAuthorize("hasAuthority('SCOPE_xxx')")` annotations
			- Tenant isolation enforced at two levels: `TenantResolutionFilter` (rejects cross-tenant path access) and `TenantOwnershipValidator` (verifies resource ownership at service level)
			- 10 OAuth2 scopes defined on the Logto API resource (`https://api.cameleer.local`), served to the frontend from `GET /api/config`

Add moat-strengthening features design spec Comprehensive design document for three defensibility features: - Live Route Debugger (replay-based, zero production impact) - Payload Flow Lineage (targeted per-processor capture + diff) - Cross-Service Trace Correlation + Topology Map (network effect) Gitea issues: cameleer/cameleer3 #57-#72 (MOAT label) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> 2026-03-29 16:14:04 +02:00			`## Related Conventions`

			- Gitea-hosted: `gitea.siegeln.net/cameleer/`
			- CI: `.gitea/workflows/` — Gitea Actions
			`- K8s target: k3s cluster at 192.168.50.86`
			- Docker builds: multi-stage, buildx with registry cache, `--provenance=false` for Gitea compatibility
			- Design system: import from `@cameleer/design-system` (Gitea npm registry)

			`## Disabled Skills`

			- Do NOT use any `gsd:*` skills in this project. This includes all `/gsd:` prefixed commands.