Architecture Diagrams

Architecture Diagram Standards

Apply these standards when creating or updating Mermaid diagrams.

Core Rules

Every Arrow Needs a Label

Unlabeled arrows force readers to guess the relationship.

%% BAD
A --> B

%% GOOD
A -->|float[] samples| B
A -->|HTTP 200| B
A -->|calls| B

No Dead Ends

Every process node needs input AND output arrows. Data doesn't disappear.

%% BAD: normalize just ends
RawData --> Normalize

%% GOOD: show what normalized data becomes
RawData -->|int16[]| Normalize -->|float[] peak=1.0| Smoother

Single Abstraction Level Per Diagram

Don't mix high-level modules with implementation functions.

Create separate diagrams for each level.

Connect All Subgraphs

Isolated subgraphs indicate missing relationships. If a subgraph modifies data elsewhere, show the arrow.

%% BAD: UI floats alone
subgraph UI
    Panel --> Slider
end
subgraph Core
    Config --> Render
end

%% GOOD: show what UI affects
subgraph UI
    Panel --> Slider
end
subgraph Core
    Config --> Render
end
Slider -->|modifies| Config

Arrow Conventions

Pick ONE meaning per diagram and state it in a legend or title:

Bidirectional: Use two arrows with separate labels, not <-->.

Client -->|request| Server
Server -->|response| Client

Required Elements

Legend

Every diagram needs a legend explaining:

• Arrow meaning (data flow vs dependency)
• Shape meanings if non-obvious
• Any color coding

%% Legend:
%% → data flow (payload type on label)
%% [box] processing function
%% [(cylinder)] persistent buffer
%% {{diamond}} decision point

Title

Descriptive title that clarifies arrow semantics:

• "Data Flow: Audio Samples to Screen" (arrows = data movement)
• "Module Dependencies" (arrows = import/call relationships)

Mermaid Syntax Reference

Labeled Edges

A -->|label| B      %% arrow with label
A -- label --> B    %% alternative syntax
A -.->|label| B     %% dotted with label
A ==>|label| B      %% thick with label

Subgraph Direction

subgraph Module[Module Name]
    direction LR
    A --> B
end

Note: Subgraph direction ignored if nodes link outside the subgraph.

Node Shapes

A[Rectangle]        %% process/function
B[(Database)]       %% persistent storage
C((Circle))         %% start/end point
D{Diamond}          %% decision
E{{Hexagon}}        %% preparation/setup
F[/Parallelogram/]  %% input/output

Verification Checklist

Before finalizing any diagram:

• Every arrow has a label describing what flows/relationship
• No orphaned nodes or subgraphs
• Every process has both input and output arrows
• Single abstraction level throughout
• Legend explains arrow and shape meanings
• Title clarifies diagram's semantic intent

Anti-patterns

Example: Complete Data Flow

flowchart LR
    subgraph Capture[Audio Capture]
        CB[Callback] -->|int16[] stereo| RB[(Ring Buffer)]
    end

    subgraph Process[Waveform Processing]
        RB -->|int16[4096]| Norm[Normalize]
        Norm -->|float[1024] peak=1.0| Smooth[Smooth]
        Smooth -->|float[2048] palindrome| Interp[CubicInterp]
    end

    subgraph Render[Visualization]
        Interp -->|Vector2[]| Draw[DrawCircular]
        Draw -->|pixels| Accum[(accumTexture)]
        Accum -->|texture| Blur[Gaussian Blur]
        Blur -->|decayed texture| Accum
        Accum -->|final frame| Screen[Display]
    end

%% Legend:
%% → data flow with payload type
%% [(name)] persistent buffer
%% [name] processing function