Skip to content

diagrams.md

Latest commit

 

History

History
104 lines (82 loc) · 3.77 KB

diagrams.md

File metadata and controls

104 lines (82 loc) · 3.77 KB
Raw

Diagrams — when to use which, and ready-made snippets

Rendered figures beat ASCII art for the key diagrams in a tutorial. Use the external drawing skills by invoking them — graphviz for arrows-and-nodes, architecture for stacked tiers. (Install info for those skills is in this repo's top-level README.md.)

Be selective. Convert the high-value diagrams (the flow main-line, the architecture stack, a dispatch switch). Leave directory trees, code snippets, and JSON examples as monospace text — turning those into figures makes them harder to read.

Which skill for which shape?

Your diagram is… Use Output
A flow / call chain / data-flow / switch dispatch (arrows between boxes) graphviz ```dot fenced block
A layered/tiered architecture (stacked colored bands) architecture embedded HTML/CSS
A directory tree, code, or JSON (leave as text) fenced code block

graphviz snippets (copy & adapt)

1. Linear flow chain — the simplest main-line hop sequence:

digraph flow {
    rankdir=LR;
    bgcolor="transparent";
    node [shape=box, style="rounded,filled", fontname="sans-serif", fontsize=11];
    edge [color="#64748b", fontsize=9];
    a [label="user input", fillcolor="#dbeafe", color="#3b82f6"];
    b [label="handler()\nfile.ext:42", fillcolor="#dcfce7", color="#16a34a"];
    c [label="effect", fillcolor="#fef9c3", color="#eab308"];
    a -> b [label="step 1"];
    b -> c [label="step 2"];
}

2. Cluster grouping — show which hops live in which subsystem/"world":

digraph grouped {
    rankdir=TB;
    bgcolor="transparent";
    compound=true;
    node [shape=box, style="rounded,filled", fontname="sans-serif", fontsize=10];
    you [label="user"];
    subgraph cluster_app {
        label="Your codebase";
        style="rounded,filled"; fillcolor="#faf5ff"; color="#c026d3";
        h1 [label="entry()\nindex.ext:10"];
        h2 [label="core()\ncore.ext:55"];
        h1 -> h2;
    }
    ext [label="external service"];
    you -> h1 [lhead=cluster_app];
    h2 -> ext [ltail=cluster_app];
}

3. Switch / dispatch — how inbound messages route back to the right waiter:

digraph dispatch {
    rankdir=LR;
    bgcolor="transparent";
    node [shape=box, style="rounded,filled", fontname="sans-serif", fontsize=10];
    inbound [label="inbound msg\nparse → read type", fillcolor="#ffedd5", color="#ea580c"];
    sw [label="switch(type)", shape=diamond, fillcolor="#fef9c3", color="#eab308"];
    a [label="type A → fire subscribers", fillcolor="#dcfce7", color="#16a34a"];
    b [label="type B → resolve pending by id", fillcolor="#dcfce7", color="#16a34a"];
    inbound -> sw; sw -> a; sw -> b;
}

graphviz gotchas

  • Cluster subgraph names must start with cluster_.
  • Quote node IDs with spaces, or use underscores: "my node" or my_node.
  • Comma-separate attributes: [shape=box, color=red].
  • For cross-cluster edges, set compound=true and use lhead=cluster_x / ltail=cluster_x.

architecture skill (layered tiers)

For a stacked, color-coded tier diagram (e.g. UI layer / logic layer / data layer), invoke the architecture skill. It emits embedded HTML (not a fenced block). Two rules from that skill that matter:

  • Embed the HTML directly in Markdown — do not wrap it in a ```html fence.
  • Keep the HTML block continuous — no blank lines inside the structure (blank lines break the rendering).

Use it when the relationship is "layers stacked on layers," not "A calls B."

Validate before shipping

  • dot blocks: pipe through dot -Tsvg (exit 0 = valid) or check the Markdown preview.
  • architecture HTML: confirm <div>/</div> counts match and there are no blank lines inside the block.