cameleer/cameleer-server
1
0
Fork 0
Code Issues 41 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(02-02): complete diagram rendering plan

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
hsiegeln
2026-03-11 16:19:09 +01:00
parent 4a31b1e815
commit dcae89f404
3 changed files with 160 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.planning/REQUIREMENTS.md
View File

@@ -39,7 +39,7 @@ Requirements for initial release. Each maps to roadmap phases. Tracked as Gitea
- [x] **DIAG-01**: Server stores `RouteGraph` definitions with content-addressable versioning (hash-based dedup) (#20) - [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-02**: Each transaction links to the `RouteGraph` version that was active at execution time (#21)
- [ ] **DIAG-03**: Server renders route diagrams from stored `RouteGraph` definitions (nodes, edges, EIP patterns) (#22) - [x] **DIAG-03**: Server renders route diagrams from stored `RouteGraph` definitions (nodes, edges, EIP patterns) (#22)
### Security ### Security

20
.planning/STATE.md
View File

@@ -26,11 +26,11 @@ See: .planning/PROJECT.md (updated 2026-03-11)
## Current Position ## Current Position
Phase: 2 of 4 (Transaction Search + Diagrams) Phase: 2 of 4 (Transaction Search + Diagrams)
Plan: 1 of 3 in current phase Plan: 2 of 3 in current phase
Status: Plan 02-01 Complete Status: Plan 02-02 Complete
Last activity: 2026-03-11 -- Completed 02-01 (Schema extension, core domain types, ingestion updates) Last activity: 2026-03-11 -- Completed 02-02 (ELK diagram rendering, SVG/JSON content negotiation, 15 tests)
Progress: [███-------] 33% Progress: [██████----] 67%
## Performance Metrics ## Performance Metrics
@@ -54,6 +54,7 @@ Progress: [███-------] 33%
| Phase 01 P02 | 7min | 2 tasks | 14 files | | Phase 01 P02 | 7min | 2 tasks | 14 files |
| Phase 01 P03 | 10min | 2 tasks | 12 files | | Phase 01 P03 | 10min | 2 tasks | 12 files |
| Phase 02 P01 | 13min | 2 tasks | 15 files | | Phase 02 P01 | 13min | 2 tasks | 15 files |
| Phase 02 P02 | 14min | 2 tasks | 10 files |
## Accumulated Context ## Accumulated Context
@@ -78,6 +79,11 @@ Recent decisions affecting current work:
- [Phase 02]: Exchange bodies/headers concatenated into single String columns for LIKE search - [Phase 02]: Exchange bodies/headers concatenated into single String columns for LIKE search
- [Phase 02]: Headers serialized to JSON via Jackson ObjectMapper (static instance) - [Phase 02]: Headers serialized to JSON via Jackson ObjectMapper (static instance)
- [Phase 02]: DiagramRenderer/DiagramLayout stubs created to resolve pre-existing compilation blocker - [Phase 02]: DiagramRenderer/DiagramLayout stubs created to resolve pre-existing compilation blocker
- [Phase 02]: ELK layered algorithm with top-to-bottom direction for route diagram layout
- [Phase 02]: JFreeSVG over Batik for lightweight server-side SVG generation
- [Phase 02]: Manual Accept header parsing -- JSON only when first preference, SVG as default
- [Phase 02]: xtext xbase lib required at runtime by ELK 0.11.0 LayeredMetaDataProvider
- [Phase 02]: Compound node children detected from RouteNode.getChildren() (matches agent graph model)
### Pending Todos ### Pending Todos
@@ -92,6 +98,6 @@ None yet.
## Session Continuity ## Session Continuity
Last session: 2026-03-11T15:15:47Z Last session: 2026-03-11T15:17:22Z
Stopped at: Completed 02-01-PLAN.md Stopped at: Completed 02-02-PLAN.md
Resume file: .planning/phases/02-transaction-search-diagrams/02-01-SUMMARY.md Resume file: .planning/phases/02-transaction-search-diagrams/02-02-SUMMARY.md

146
.planning/phases/02-transaction-search-diagrams/02-02-SUMMARY.md Normal file
View File

@@ -0,0 +1,146 @@
---
phase: 02-transaction-search-diagrams
plan: 02
subsystem: api
tags: [elk, jfreesvg, svg, diagram, layout, content-negotiation]
requires:
- phase: 01-ingestion-pipeline
provides: DiagramRepository with findByContentHash for loading RouteGraph definitions
provides:
- DiagramRenderer interface in core module for SVG and JSON layout output
- ElkDiagramRenderer implementation using ELK layered algorithm and JFreeSVG
- DiagramRenderController with Accept header content negotiation
- Color-coded node rendering matching route-diagram-example.html style
- Compound node support for nested processors (CHOICE, SPLIT, TRY_CATCH)
affects: [02-03, ui-rendering, execution-overlay]
tech-stack:
added: [org.eclipse.elk.core:0.11.0, org.eclipse.elk.alg.layered:0.11.0, org.jfree.svg:5.0.7, org.eclipse.xtext.xbase.lib:2.37.0]
patterns: [ELK graph construction, JFreeSVG rendering, manual Accept header content negotiation]
key-files:
created:
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/diagram/DiagramRenderer.java
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/diagram/DiagramLayout.java
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/diagram/PositionedNode.java
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/diagram/PositionedEdge.java
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/diagram/ElkDiagramRenderer.java
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/controller/DiagramRenderController.java
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/config/DiagramBeanConfig.java
- cameleer3-server-app/src/test/java/com/cameleer3/server/app/diagram/ElkDiagramRendererTest.java
- cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/DiagramRenderControllerIT.java
modified:
- cameleer3-server-app/pom.xml
key-decisions:
- "Used ELK layered algorithm with top-to-bottom direction for route diagram layout"
- "JFreeSVG for server-side SVG generation (lightweight, no Batik dependency)"
- "Manual Accept header parsing for content negotiation -- JSON only when first preference, SVG as default"
- "Added xtext xbase lib runtime dependency required by ELK 0.11.0 LayeredMetaDataProvider"
- "Compound nodes detected via RouteNode.children rather than edge topology analysis"
patterns-established:
- "DiagramRenderer interface in core, implementation in app -- swappable rendering backend"
- "Accept header content negotiation: check first media type preference, default to SVG"
- "NodeType color mapping via EnumSet groupings for efficient lookup"
requirements-completed: [DIAG-03]
duration: 14min
completed: 2026-03-11
---
# Phase 2 Plan 2: Diagram Rendering Summary
**ELK-based route diagram rendering with color-coded SVG output, JSON layout API, and compound node swimlanes via content-negotiated REST endpoint**
## Performance
- **Duration:** 14 min
- **Started:** 2026-03-11T15:03:12Z
- **Completed:** 2026-03-11T15:17:22Z
- **Tasks:** 2
- **Files modified:** 10
## Accomplishments
- Route diagrams render as color-coded top-to-bottom SVG with ELK layered algorithm
- JSON layout API returns positioned nodes and edges for client-side rendering
- Compound nodes (CHOICE, SPLIT, TRY_CATCH) render in swimlane containers with children
- Content negotiation: Accept: application/json returns JSON, everything else defaults to SVG
- 11 unit tests and 4 integration tests verify layout, colors, content types, and 404 handling
## Task Commits
Each task was committed atomically:
1. **Task 1: Add ELK/JFreeSVG dependencies and create core diagram rendering interfaces** - `6df7450` (feat)
2. **Task 2: Implement ElkDiagramRenderer, DiagramRenderController, and integration tests** - `c1bc32d` (feat, TDD)
## Files Created/Modified
- `cameleer3-server-core/.../diagram/DiagramRenderer.java` - Renderer interface with renderSvg and layoutJson
- `cameleer3-server-core/.../diagram/DiagramLayout.java` - Layout record (width, height, nodes, edges)
- `cameleer3-server-core/.../diagram/PositionedNode.java` - Node record with position, dimensions, children
- `cameleer3-server-core/.../diagram/PositionedEdge.java` - Edge record with waypoints
- `cameleer3-server-app/.../diagram/ElkDiagramRenderer.java` - ELK + JFreeSVG implementation (~400 lines)
- `cameleer3-server-app/.../controller/DiagramRenderController.java` - GET /api/v1/diagrams/{hash}/render
- `cameleer3-server-app/.../config/DiagramBeanConfig.java` - Spring bean wiring for DiagramRenderer
- `cameleer3-server-app/pom.xml` - Added ELK, JFreeSVG, xtext dependencies
- `cameleer3-server-app/.../diagram/ElkDiagramRendererTest.java` - 11 unit tests
- `cameleer3-server-app/.../controller/DiagramRenderControllerIT.java` - 4 integration tests
## Decisions Made
- Used ELK layered algorithm (org.eclipse.elk.alg.layered) -- well-maintained, supports compound nodes natively
- JFreeSVG over Batik -- lightweight, no transitive dependency bloat, sufficient for server-side SVG generation
- Manual Accept header parsing instead of Spring content negotiation -- simpler, avoids Spring's default JSON preference when Accept includes wildcards
- Added xtext xbase lib as runtime dependency -- ELK 0.11.0's LayeredMetaDataProvider references CollectionLiterals at class init time
- Compound node children detected from RouteNode.getChildren() rather than edge topology -- cleaner and matches the agent's graph model
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] Added xtext xbase lib dependency for ELK compatibility**
- **Found during:** Task 2 (ElkDiagramRenderer implementation)
- **Issue:** ELK 0.11.0 LayeredMetaDataProvider references org.eclipse.xtext.xbase.lib.CollectionLiterals at class initialization, causing NoClassDefFoundError
- **Fix:** Added org.eclipse.xtext:org.eclipse.xtext.xbase.lib:2.37.0 dependency to app pom.xml
- **Files modified:** cameleer3-server-app/pom.xml
- **Verification:** All unit tests pass after adding dependency
- **Committed in:** c1bc32d (Task 2 commit)
**2. [Rule 1 - Bug] Fixed content negotiation default format**
- **Found during:** Task 2 (integration test for default Accept header)
- **Issue:** TestRestTemplate sends Accept: text/plain, application/json, */* by default; simple contains("application/json") check returned JSON instead of SVG
- **Fix:** Changed to check only the first media type in Accept header -- JSON only when explicitly first preference
- **Files modified:** DiagramRenderController.java
- **Verification:** Integration test getWithNoAcceptHeader_defaultsToSvg passes
- **Committed in:** c1bc32d (Task 2 commit)
**3. [Rule 1 - Bug] Adapted to actual NodeType enum naming (EIP_ prefix)**
- **Found during:** Task 2 (ElkDiagramRenderer implementation)
- **Issue:** Plan referenced CHOICE, SPLIT etc. but actual enum values are EIP_CHOICE, EIP_SPLIT etc.
- **Fix:** Used correct enum names from decompiled cameleer3-common jar in all color mapping sets
- **Files modified:** ElkDiagramRenderer.java
- **Verification:** Unit tests verify correct colors for endpoint and processor nodes
- **Committed in:** c1bc32d (Task 2 commit)
---
**Total deviations:** 3 auto-fixed (2 bugs, 1 blocking dependency)
**Impact on plan:** All auto-fixes necessary for correctness. No scope creep.
## Issues Encountered
- ELK 0.11.0 has an undeclared runtime dependency on xtext xbase lib -- resolved by adding explicit dependency
- RouteEdge.EdgeType uses FLOW/BRANCH/ERROR/CROSS_ROUTE (not NORMAL as plan implied) -- adapted tests accordingly
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- Diagram rendering complete, ready for execution overlay in UI (v2)
- DiagramRenderer interface can be swapped for alternative implementations
- JSON layout format suitable for client-side interactive rendering
---
*Phase: 02-transaction-search-diagrams*
*Completed: 2026-03-11*