moomaid-diagramming

name	moomaid-diagramming
description	Select, write, and render Mermaid diagrams that explain source code, module boundaries, system architecture, request flows, data models, project plans, or Git history. Use when a user asks which diagram best communicates a technical design, asks for an architecture or codebase explanation, or needs Mermaid source and an ASCII/SVG rendering with Moomaid.

Moomaid Diagramming

Explain one user question with one primary diagram. Start from the question, not a preferred Mermaid syntax. Use a second diagram only when the first cannot show both the static structure and the important behavior.

Choose the diagram

User needs to understand	Use	Show
System, service, package, or module boundaries	flowchart with subgraph	Components, ownership, dependencies, and direction of data or control
One request, command, or event at runtime	sequenceDiagram	Participants, message order, branches, retries, and notable async boundaries
Public APIs, types, and code-level responsibilities	classDiagram	Types, important fields or operations, and relationships; omit implementation detail
Data ownership and cardinality	erDiagram	Entities, keys only when relevant, and one-to-one/one-to-many relationships
A domain object's legal lifecycle	stateDiagram-v2	States, triggers, guards, and terminal states
Architecture ideas, concerns, or a hierarchy before dependencies matter	mindmap	A root topic and progressively indented concepts
A user's experience across product or system stages	journey	Sections, tasks, scores, and actors; do not use it for request messages
A small, static composition of a whole	pie	Named shares and values; use a table instead when exact comparison matters
A small number of historical or product milestones	timeline	Dated milestones in chronological order
Planned work, dates, status, and duration	gantt	Tasks, schedule, and execution status; do not use for runtime behavior
Branching and commits	gitGraph	Branches, merges, and releases; do not use it as a project schedule

Use a flowchart for a code control path when the ordering is simple and no participant needs its own lifeline. Use a sequenceDiagram when the reader must see who initiates each step or when concurrent/alternative paths matter.

For an architecture explanation that also needs a request walkthrough, render two diagrams in this order:

1. A flowchart with subgraph for the system overview.
2. A sequenceDiagram for the representative request.

Do not combine deployment topology, entity cardinality, and runtime ordering in one diagram. Split them into focused diagrams instead.

Build an explanatory diagram

1. State the reader's question and scope in one sentence. Name what is intentionally outside the diagram when that boundary could be confusing.
2. Choose stable, short node IDs and labels in the user's language. Prefer responsibilities such as Auth API or Persist order over implementation trivia such as filenames or function-local variables.
3. Keep the primary view to roughly 5–12 visible nodes. Group related nodes in subgraph blocks before adding edges across boundaries.
4. Put edge labels on relationships that need a verb, protocol, data type, or cardinality. Leave obvious edges unlabeled. In an ASCII architecture view, keep cross-subgraph edges unlabeled and explain their verbs in the prose.
5. Use only facts available in the supplied code, design, or stated assumptions. Mark inferred relationships as assumptions in the prose.

Use these patterns as starting points.

Component architecture

Use a left-to-right flowchart for dependencies. Make a subgraph match an owned boundary: application, service, package, or infrastructure domain.

flowchart LR
  subgraph Web
    UI[Browser]
  end
  subgraph API
    Handler[Request handler]
    Service[Order service]
  end
  DB[(Orders)]

  UI --> Handler
  Handler --> Service
  Service --> DB

Runtime request path

Use a sequence diagram after the overview when message ordering is the point. Keep each message an observable operation; use alt or par only for real branches or concurrency.

sequenceDiagram
  participant UI as Browser
  participant API as Order API
  participant DB as Orders
  UI->>API: POST /orders
  API->>DB: create order
  DB-->>API: order id
  API-->>UI: 201 Created

Code or domain model

Use a class diagram for an API or type model, and an ER diagram when data cardinality is the question. Do not use a class diagram merely because the implementation language has classes.

classDiagram
  class OrderService {
    +createOrder()
  }
  class OrderRepository {
    +insert()
  }
  OrderService --> OrderRepository

Render and inspect

Save each source as a .mmd file. Use ASCII as the primary output only for a compact diagram with short labels. Use SVG as the primary output for a diagram with multiple subgraphs, long labels, or several cross-boundary edges. Render both when practical; never present an ASCII diagram whose labels cross borders or other edges.

moon runwasm src/cmd/skill --format ascii < architecture.mmd
moon runwasm src/cmd/skill --format svg < architecture.mmd > architecture.svg

For an installed Mooncakes package, replace the local package path with mizchi/moomaid/cmd/skill@<version>. The skill accepts only --format ascii|svg and writes one rendered artifact to standard output.

Before presenting a diagram, check that labels are readable in the chosen format, every edge has a clear direction, and the diagram answers the declared question without requiring the reader to inspect source code first.

Present the explanation

Lead with the conclusion, then show the diagram and three to five short points that explain the highest-value relationships. Include the Mermaid source when the user may want to edit it. State assumptions, omitted systems, and the next diagram that would answer a different question rather than overloading the current one.