STD-020: Diagram Catalog Management

The diagram catalog manages 77+ diagrams across 9 categories: Architecture, Network, Security, Flows, Projects, TAC Cases, Trackers, Monad, and Screenshots. D2 is the primary authoring tool, SVG the required output format. Source files live in images/diagrams/ or examples/diagrams/ and are rendered via Kroki during Antora builds. The catalog is not a dumping ground — every diagram has a category, a naming convention, and an index entry.

Principles

  1. Every diagram is indexed. A diagram without a catalog entry is invisible. When a diagram is created, it MUST be added to its category index page and the gallery index. Orphaned diagrams are technical debt.

  2. Source is truth, output is artifact. The .d2, .dot, .mmd, or .puml source file is what gets versioned and reviewed. SVG output is generated during build. Never commit generated SVGs when source exists.

  3. Tool follows purpose. Each diagramming tool has a domain where it excels. Selection is not preference — it is a function of what the diagram communicates. The tool selection guide below is normative.

  4. Naming is navigation. Kebab-case with category prefix makes diagrams findable via glob and grep without opening a browser. The filename alone should communicate category and subject.

Tool Selection Guide

Tool Format Best For

D2

.d2

Architecture diagrams, infrastructure topology, network layouts, service dependencies. Primary tool — use unless another tool is clearly better suited.

Graphviz (dot)

.dot

Hierarchies, module trees, dependency graphs, org charts. Excels at automatic layout of directed graphs.

Mermaid

.mmd

Sequence diagrams, flowcharts, state machines. Lightweight for simple flows where layout control is not critical.

PlantUML

.puml

UML diagrams (class, activity, use case). Use when UML notation is the explicit requirement.

When in doubt, use D2. It handles the widest range of diagram types with the best aesthetic defaults.

Naming Convention

All diagram source files MUST use kebab-case with category prefix:

<category>-<subject>.<ext>

Examples:

architecture-domus-docs-pipeline.d2
network-vlan-topology.d2
security-eaptls-certificate-flow.dot
flows-antora-build-pipeline.mmd
projects-thinkpad-deploy-phases.d2
tac-chla-8021x-auth-sequence.mmd
trackers-certification-progress.d2
monad-category-theory-functor.puml

Rules:

  • Category prefix MUST match one of the 9 established categories (or a newly created category per the procedure below).

  • Subject portion uses kebab-case, descriptive enough to identify the diagram without opening it.

  • Extension MUST match the tool: .d2, .dot, .mmd, .puml.

Source Locations

Location Content

images/diagrams/

Rendered output (SVG) and diagrams included via image:: in pages

examples/diagrams/

Source files (.d2, .dot, .mmd, .puml) included via include::example$ or used as build inputs

Build Commands

make diagrams          # Build all diagrams (all formats)
make diagrams-d2       # Build D2 diagrams only
make diagrams-dot      # Build Graphviz diagrams only
make diagrams-mmd      # Build Mermaid diagrams only
make diagrams-puml     # Build PlantUML diagrams only

Kroki server management (required for D2 and Mermaid rendering during make builds):

make kroki             # Start Kroki server
make kroki-stop        # Stop Kroki server

The domus-docs hub Makefile runs kroki-stop automatically after builds (all: diagrams local kroki-stop). For spoke-only builds in this repo, manage Kroki manually.

Category Index Pages

Each category has an index page at pages/reference/diagrams/<category>.adoc that MUST include:

  • A diagram count for that category

  • A table listing all diagrams with columns: Name, Description, Tool, Source File

= Architecture Diagrams
:description: Architecture diagram catalog — N diagrams
:navtitle: Architecture
:icons: font

== Catalog (N diagrams)

[cols="2,3,1,2"]
|===
| Name | Description | Tool | Source

| Domus Docs Pipeline
| End-to-end documentation build and deploy flow
| D2
| `architecture-domus-docs-pipeline.d2`

| Hub-Spoke Architecture
| Antora aggregator and spoke repository relationships
| D2
| `architecture-hub-spoke.d2`
|===

Gallery Index

The gallery index at pages/reference/diagrams/index.adoc provides a single-page overview of the entire catalog.

Required Quick Stats Block

== Quick Stats

[cols="1,3"]
|===
| Metric | Value

| Total Diagrams | 77+
| Primary Tool | D2
| Output Format | SVG
| Source Location | `examples/diagrams/`, `images/diagrams/`
| Categories | 9
|===

Required Category Summary Table

[cols="2,1,3"]
|===
| Category | Count | Description

| xref:reference/diagrams/architecture.adoc[Architecture]
| NN
| System topology, service dependencies, build pipelines

| xref:reference/diagrams/network.adoc[Network]
| NN
| VLAN layouts, routing, firewall rules

| ...
|===

Category Management

Adding a new category (the 10th or subsequent):

  1. Create the source directory if not already present: examples/diagrams/<category>/ or add files to the existing flat structure with the new category prefix.

  2. Create the category index page: pages/reference/diagrams/<category>.adoc following the category index template above.

  3. Update the gallery index: Add the new category row to the summary table in pages/reference/diagrams/index.adoc. Update the Quick Stats category count.

  4. Update the nav file: Add the new category under the Diagrams section.

  5. Update this standard: Add the new category to the naming convention and categories list.

  6. Build check: make 2>&1 | grep -E "WARN|ERROR"

Categories Reference

Category Scope

Architecture

System designs, build pipelines, deployment topology, service maps

Network

VLAN layouts, routing tables, firewall rules, IP addressing

Security

Certificate flows, authentication sequences, trust chains

Flows

Process flows, build sequences, data pipelines

Projects

Project-specific diagrams (deploy phases, migration paths)

TAC Cases

Vendor case diagrams (authentication failures, topology for support)

Trackers

Progress tracking, certification timelines, project Gantt charts

Monad

Category theory, functional programming, type system diagrams

Screenshots

Captured UI states, configuration screens, evidence for case studies

Compliance

Check Method Pass Criterion

Source file uses kebab-case with category prefix

ls examples/diagrams/ images/diagrams/

All files match <category>-<subject>.<ext> pattern

Diagram listed in category index

Compare source files against category page table rows

Every source file has a corresponding table entry

Gallery index Quick Stats current

Compare total count against actual diagram count

Counts match within reasonable tolerance

SVG output format

file images/diagrams/*.svg

All rendered diagrams are SVG

Kroki available for build

make kroki && curl -s localhost:8000/

Kroki responds

Build clean

make 2>&1 | grep -E 'WARN|ERROR'

Zero output

New categories follow procedure

Visual inspection of category page, gallery index, nav

All four artifacts updated

Related