cameleer-server/.planning/REQUIREMENTS.md

# Requirements: Cameleer3 Server

**Defined:** 2026-03-11
**Core Value:** Users can reliably search and find any transaction across all connected Camel instances — by any combination of state, time, duration, or content — even at millions of transactions per day with 30-day retention.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases. Tracked as Gitea issues.

### Data Ingestion

- [x] **INGST-01**: Server accepts `RouteExecution` (single or array) via `POST /api/v1/data/executions` and returns `202 Accepted` (#1)
- [x] **INGST-02**: Server accepts `RouteGraph` (single or array) via `POST /api/v1/data/diagrams` and returns `202 Accepted` (#2)
- [x] **INGST-03**: Server accepts metrics snapshots via `POST /api/v1/data/metrics` and returns `202 Accepted` (#3)
- [x] **INGST-04**: Ingestion uses in-memory batch buffer with configurable flush interval/size for ClickHouse writes (#4)
- [x] **INGST-05**: Server returns `503 Service Unavailable` when write buffer is full (backpressure) (#5)
- [x] **INGST-06**: ClickHouse TTL automatically expires data after 30 days (configurable) (#6)

### Transaction Search

- [x] **SRCH-01**: User can search transactions by execution status (COMPLETED, FAILED, RUNNING) (#7)
- [x] **SRCH-02**: User can search transactions by date/time range (startTime, endTime) (#8)
- [x] **SRCH-03**: User can search transactions by duration range (min/max milliseconds) (#9)
- [x] **SRCH-04**: User can search transactions by correlationId to find all related executions across instances (#10)
- [x] **SRCH-05**: User can full-text search across message bodies, headers, error messages, and stack traces (#11)
- [ ] **SRCH-06**: User can view transaction detail with nested processor execution tree (#12)

### Agent Management

- [ ] **AGNT-01**: Agent registers via `POST /api/v1/agents/register` with bootstrap token, receives JWT + server public key (#13)
- [ ] **AGNT-02**: Server maintains agent registry with LIVE/STALE/DEAD lifecycle based on heartbeat timing (#14)
- [ ] **AGNT-03**: Agent sends heartbeat via `POST /api/v1/agents/{id}/heartbeat` every 30s (#15)
- [ ] **AGNT-04**: Server pushes `config-update` events to agents via SSE with Ed25519 signature (#16)
- [ ] **AGNT-05**: Server pushes `deep-trace` commands to agents via SSE for specific correlationIds (#17)
- [ ] **AGNT-06**: Server pushes `replay` commands to agents via SSE with signed replay tokens (#18)
- [ ] **AGNT-07**: SSE connection includes `ping` keepalive and supports `Last-Event-ID` reconnection (#19)

### Route Diagrams

- [x] **DIAG-01**: Server stores `RouteGraph` definitions with content-addressable versioning (hash-based dedup) (#20)
- [x] **DIAG-02**: Each transaction links to the `RouteGraph` version that was active at execution time (#21)
- [x] **DIAG-03**: Server renders route diagrams from stored `RouteGraph` definitions (nodes, edges, EIP patterns) (#22)

### Security

- [ ] **SECU-01**: All API endpoints (except health and register) require valid JWT Bearer token (#23)
- [ ] **SECU-02**: JWT refresh flow via `POST /api/v1/agents/{id}/refresh` (#24)
- [ ] **SECU-03**: Server generates Ed25519 keypair; public key delivered at registration (#25)
- [ ] **SECU-04**: All config-update and replay SSE payloads are signed with server's Ed25519 private key (#26)
- [ ] **SECU-05**: Bootstrap token from `CAMELEER_AUTH_TOKEN` env var validates initial agent registration (#27)

### REST API

- [x] **API-01**: All endpoints follow the protocol v1 path structure (`/api/v1/...`) (#28)
- [x] **API-02**: API documented via OpenAPI/Swagger (springdoc-openapi) (#29)
- [x] **API-03**: Server includes `GET /api/v1/health` endpoint (#30)
- [x] **API-04**: All requests validated for `X-Cameleer-Protocol-Version: 1` header (#31)
- [x] **API-05**: Server accepts unknown JSON fields for forward compatibility (#32)

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Web UI

- **UI-01**: Transaction search form and result list view
- **UI-02**: Transaction detail view with activity drill-down
- **UI-03**: Route diagram visualization with execution overlay
- **UI-04**: Agent status overview dashboard
- **UI-05**: Dashboard with volume/error trend charts

### Advanced Search

- **ASRCH-01**: Cursor-based pagination for large result sets
- **ASRCH-02**: Saved search queries

## Out of Scope

| Feature | Reason |
|---------|--------|
| Mobile app | Web UI sufficient for ops/dev users |
| Log aggregation | Transaction-level observability, not a log collector |
| APM/metrics dashboards | Focused on Camel route transactions, not general application metrics |
| Multi-tenancy | Single-tenant deployment per environment |
| Kafka transport | HTTP POST ingestion is the primary path; Kafka is agent-side concern |
| Custom dashboards | Fixed dashboard views; no user-configurable widgets |
| Real-time firehose | Not a streaming platform; query-based access |
| AI root cause analysis | Out of scope for v1; focus on search and visualization |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| INGST-01 (#1) | Phase 1 | Pending |
| INGST-02 (#2) | Phase 1 | Pending |
| INGST-03 (#3) | Phase 1 | Pending |
| INGST-04 (#4) | Phase 1 | Pending |
| INGST-05 (#5) | Phase 1 | Pending |
| INGST-06 (#6) | Phase 1 | Pending |
| SRCH-01 (#7) | Phase 2 | Pending |
| SRCH-02 (#8) | Phase 2 | Pending |
| SRCH-03 (#9) | Phase 2 | Pending |
| SRCH-04 (#10) | Phase 2 | Pending |
| SRCH-05 (#11) | Phase 2 | Pending |
| SRCH-06 (#12) | Phase 2 | Pending |
| AGNT-01 (#13) | Phase 3 | Pending |
| AGNT-02 (#14) | Phase 3 | Pending |
| AGNT-03 (#15) | Phase 3 | Pending |
| AGNT-04 (#16) | Phase 3 | Pending |
| AGNT-05 (#17) | Phase 3 | Pending |
| AGNT-06 (#18) | Phase 3 | Pending |
| AGNT-07 (#19) | Phase 3 | Pending |
| DIAG-01 (#20) | Phase 2 | Pending |
| DIAG-02 (#21) | Phase 2 | Pending |
| DIAG-03 (#22) | Phase 2 | Pending |
| SECU-01 (#23) | Phase 4 | Pending |
| SECU-02 (#24) | Phase 4 | Pending |
| SECU-03 (#25) | Phase 4 | Pending |
| SECU-04 (#26) | Phase 4 | Pending |
| SECU-05 (#27) | Phase 4 | Pending |
| API-01 (#28) | Phase 1 | Pending |
| API-02 (#29) | Phase 1 | Pending |
| API-03 (#30) | Phase 1 | Pending |
| API-04 (#31) | Phase 1 | Pending |
| API-05 (#32) | Phase 1 | Pending |

**Coverage:**
- v1 requirements: 32 total
- Mapped to phases: 32
- Unmapped: 0

---
*Requirements defined: 2026-03-11*
*Last updated: 2026-03-11 after roadmap creation*