31 lines
2.6 KiB
Markdown
31 lines
2.6 KiB
Markdown
# Format and tool selection
|
|
|
|
The harness separates **semantic source**, **editable source**, and **publication artifact**.
|
|
|
|
| Format | Best use | Strengths | Failure mode / constraint |
|
|
|---|---|---|---|
|
|
| VizSpec JSON | Canonical meaning and evidence | Tool-neutral, lintable, traceable, deterministic | Not intended for manual presentation |
|
|
| SVG | Default publication in web/Markdown/docs | Scalable, searchable, accessible metadata, text diff | Keep scripts, external references, and `foreignObject` out |
|
|
| draw.io / diagrams.net | Enterprise architecture and official cloud stencils | Familiar manual editing, strong connector semantics, broad vendor libraries | Plain exported SVG loses editing semantics unless diagram data/source is preserved |
|
|
| Mermaid | Sequence, state, ERD, compact flow near Markdown | Small textual source, GitHub/GitLab rendering, easy review | Layout control and accessibility vary by renderer/version |
|
|
| D2 | Auto-laid-out architecture and data flow | Concise source, SVG-first output, good layout defaults | Requires D2 for native rendering beyond generated source |
|
|
| Graphviz DOT | Dense dependency and relationship graphs | Mature graph layout and crossing reduction | Less suitable for manual architecture storytelling |
|
|
| Excalidraw | Concept sketch, workshop, informal explanation | Fast visual ideation and approachable editing | Hand-drawn semantics can imply lower precision; JSON diffs are noisy |
|
|
| Structurizr DSL / C4 | Multiple architecture views from one model | One model can generate context/container/component/deployment views | Introduce when the repository needs a durable multi-view architecture model |
|
|
| PlantUML/Kroki | Broad diagrams-as-code ecosystems | Many diagram families and server rendering | Server/runtime dependency and syntax-specific portability |
|
|
| PNG | Compatibility fallback | Universal display | Raster, weak accessibility, poor scaling; never the only source |
|
|
| PDF | Print and controlled distribution | Stable pagination and vector output | Weak as an editable or repository-native source |
|
|
|
|
## Default policy
|
|
|
|
1. Always preserve VizSpec JSON.
|
|
2. Always publish SVG unless the target platform forbids it.
|
|
3. Preserve one editable source selected by intent:
|
|
- architecture/deployment/network → draw.io;
|
|
- sequence/state/ERD/compact flow → Mermaid;
|
|
- data-flow/auto-layout architecture → D2;
|
|
- dense dependency → DOT;
|
|
- conceptual workshop visual → Excalidraw.
|
|
4. Generate PNG or PDF only as downstream delivery formats.
|
|
5. Use official provider icon packs only for explicitly named services; keep the provider's product label visible.
|