# 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:

```plantuml
@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