3d-components/conversation-summary.md

Conversation summary — PlantUML isometric 3D renderer

Context

This conversation explored generating interactive 3D/isometric renderings of embedded system architecture diagrams, with a specific focus on an automotive ECU use case. The team uses PlantUML and self-hosts the PlantUML server.

---

System being modelled

Three top-level ECUs: A, B, and C.

ECU B contains:

• A Connector and an Adapter for each of ECU A and ECU C (two parallel lanes)
• Both adapters feed into a single Logic component
• Inside Logic, a sequential sub-flow: a → b → c

PlantUML source:

@startuml
component "ECU A" as A
component "ECU C" as C

component "ECU B" as B {
  component "Connector A" as ConA
  component "Adapter A" as AdpA
  component "Connector C" as ConC
  component "Adapter C" as AdpC
  component "Logic" as L {
    component "a" as La
    component "b" as Lb
    component "c" as Lc
    La --> Lb
    Lb --> Lc
  }
  ConA --> AdpA
  ConC --> AdpC
  AdpA --> L
  AdpC --> L
}

A --> ConA
C --> ConC
@enduml

---

What was built

An interactive isometric 3D renderer that:

1. Parses PlantUML component diagram syntax client-side (no server required for the parser itself)
2. Renders an isometric SVG — each component is a 3-faced isometric block with color coding by component type
3. Supports drill-down zoom — clicking a component with nested children transitions to an internal view, with a breadcrumb trail for navigation
4. Color scheme by component type:
   • Gray → ECU / top-level components
   • Teal → Connectors
   • Amber → Adapters
   • Purple → Logic components
   • Coral → Sequence steps (short labels like a, b, c)

A standalone plantuml-3d-renderer.html file was produced — open it directly in any browser or VSCode Live Preview.

---

Architecture decisions

Parser approach

The client-side parser handles:

• component "Label" as alias { ... } — with or without braces
• component alias { ... } — unlabelled alias form
• alias --> alias : optional label — directed connections
• Arbitrary nesting depth

For production: POST the .puml source to your self-hosted PlantUML server's /json endpoint and drive the renderer from the returned AST instead. This handles edge cases (stereotypes, notes, skinparam, grouped interfaces) that the lightweight client-side parser skips.

Rendering

• Pure SVG, no dependencies
• Isometric projection: each block has top/left/right faces using CSS custom properties for colors
• Dark mode automatic via prefers-color-scheme
• Zoom levels are discrete view transitions (not CSS transforms) — each level is a full redraw of the SVG for the selected node's children

---

DSL alternatives considered

Tool	License	Notes
PlantUML	GPL / LGPL (jar)	Team already uses it. Self-hosting fine for commercial internal use. Get a free Professional Edition key to suppress ads.
Mermaid	MIT	Simplest license, no restrictions. Less expressive for deep nesting.
D2	MPL 2.0	Clean syntax, good nesting. TALA layout engine requires paid license for commercial use.
Structurizr DSL	Apache 2.0	C4-model based. Server prebuilt binaries need a license; build from source is free.
ArchiMate	Non-commercial free / annual commercial license	The Archi tool (MIT), but the language spec requires a commercial license from The Open Group for commercial use.
SysML	Open source (OMG derived)	Semantically correct for ECU/embedded systems. Heavy tooling (Cameo, Papyrus). Eclipse SysON is open source.
AADL	SAE standard (spec costs money; OSATE tooling is open source)	Best fit for automotive embedded. Steep learning curve.

Recommendation: Stay on PlantUML. The team's existing knowledge compounds in value faster than any migration would justify — unless moving toward full MBSE (model-based systems engineering) with SysML or AADL.

---

Next steps / open threads

• Wire the renderer to the self-hosted PlantUML /json endpoint instead of the client-side parser
• Add animated connection flows (data flowing between components)
• Support PlantUML stereotypes (<<ECU>>, <<connector>>) as an explicit color override mechanism, removing the label-inference heuristic
• Consider a VSCode extension wrapper: watch .puml files, re-render on save, show isometric view in a side panel
• Explore Three.js for true 3D with orbit/zoom controls, for stakeholder presentation use cases

---

How to continue in VSCode

1. Open plantuml-3d-renderer.html with Live Preview or any browser
2. Start a new Claude chat (Claude Code CLI or Copilot+Claude) and paste this summary
3. The renderer source is self-contained — all logic is in the single HTML file
4. Key function to extend: parsePuml(src) for parser changes, drawLevel(node) for rendering changes, guessColor(node) for color mapping changes