PlantUML Layout Rules (diagram style guide)

# PlantUML Layout Rules

Goals: minimal line crossings, shortest possible links, reviewable diagrams for ASPICE work products (SYS.3 etc.). Source: UDS Security example, applied to Examples/Diagrams/*.puml.

## Rules

1. **Declare elements in data-flow order.** PlantUML/dot ranks by declaration order; a pipeline declared in flow order needs no manual pinning.
2. **Hub in the middle.** The most-connected element (e.g. SSA-AP) sits centrally; single-link peripherals go to the edges.
3. **Left-to-right for layered stacks**: `left to right direction` for component/context diagrams (request path flows left to right). Top-to-bottom for state machines (main flow downward).
4. **Edge-local links only.** Every link connects adjacent layers. If a link would span more than one layer, re-order declarations instead of drawing a long line.
5. **Externals at the boundary.** Off-item actors/nodes (tester, VSM, PKI) are declared first and never interleaved with internal components.
6. **Direction hints instead of fights.** Use `-down->`, `-right->`, `-up->` and `-[hidden]right->` to pin placement; never rearrange model logic for layout.
7. **Short labels.** Max 3 short lines per box; compress requirement IDs (RQ-002); long prose belongs in the DOORS workbook, not the diagram.
8. **Sequence diagrams: lifelines in interaction order**, messages only between adjacent lifelines, returns as `-->`, `autonumber` for review comments, `==` phase separators.
9. **Max one line crossing per diagram.** If more, split the diagram.

## PlantUML gotchas found

- A physical line starting with `|` is parsed as a divider -> syntax error. Multi-line labels must be ONE logical line using `\n`.
- Square brackets `[...]` inside component display names break parsing - use parentheses.
- Hidden directional arrows need the final `>`: `-[hidden]right->`.
- The `-ttxt` ASCII exporter crashes (NPE) on `note` elements in left-to-right mode; PNG output is unaffected.
- Render locally: `java -jar plantuml.jar -tpng -charset UTF-8 <files>` (plantuml.jar v1.2024.7).

id: c070e8144cd34d859e6521ab9edaab85
parent_id: 49fa12562d8744a9abb8f81815faf180
created_time: 2026-08-19T07:34:08.654Z
updated_time: 2026-08-19T07:34:08.654Z
is_conflict: 0
latitude: 0.00000000
longitude: 0.00000000
altitude: 0.0000
author: 
source_url: 
is_todo: 0
todo_due: 0
todo_completed: 0
source: joplin-desktop
source_application: net.cozic.joplin-desktop
application_data: 
order: 1787124848654
user_created_time: 2026-08-19T07:34:08.654Z
user_updated_time: 2026-08-19T07:34:08.654Z
encryption_cipher_text: 
encryption_applied: 0
markup_language: 1
is_shared: 0
share_id: 
conflict_original_id: 
master_key_id: 
user_data: 
deleted_time: 0
is_locked: 0
extracted_resource_ids: 
type_: 1