| name | architecture-diagram-draw |
| description | Draw clear, audience-appropriate software architecture diagrams and their companion sequence diagrams that communicate scope, structure, interfaces, and relationships without mixing abstraction levels or mixing static structure with runtime flow. |
architecture-diagram-draw
Purpose
Use this skill to produce software architecture diagrams that are easy to read, accurate enough to support engineering discussion, and scoped to a specific audience and decision. When the topic involves runtime behavior (request lifecycles, agent loops, event flows), the deliverable is typically a pair: a static layered architecture diagram plus a dynamic sequence diagram.
This skill is for communication first, not for drawing everything that exists. A good architecture diagram should answer a concrete question, at a single abstraction level, with explicit semantics. A good sequence diagram should answer "how does one request traverse those structures over time" — and nothing else.
When to use
Use this skill when the user asks to:
- draw or redesign a software architecture diagram
- draw a sequence diagram for a request lifecycle / agent loop / event flow, or the paired "architecture + sequence" set for a system
- explain a system visually
- prepare a diagram for a report, review, onboarding, design doc, pitch, or presentation
- convert a textual system description into a context / container / component / deployment / runtime diagram
- clean up an existing messy architecture diagram
- decide what to include or omit in an architecture diagram
Do not use this skill when the user actually needs:
- a sequence of implementation tasks instead of a diagram
- a full UML class model
- source-code-level documentation
- a product UI wireframe or user flow rather than system architecture
Core objective
Always optimize for these outcomes:
- The intended audience can understand the diagram quickly.
- The diagram answers one main question.
- The diagram uses one primary abstraction level.
- Every visual element has explicit meaning.
- The diagram can stand mostly on its own, but is supported by short text where needed.
- The diagram remains maintainable as the system evolves.
Non-negotiable principles
1. Start with audience and question
Before drawing anything, identify:
- who the diagram is for
- what decision / explanation / review it supports
- what the reader should understand after looking at it
If the user does not specify this, infer the most practical audience and state your assumption.
2. One diagram, one topic, one level
Do not mix business context, service internals, deployment nodes, runtime flow, and data details into one picture unless the user explicitly needs a hybrid view.
Default to a single dominant level per diagram:
- System Context: the system and the world around it
- Container: major applications / services / data stores inside the system
- Component: important internal building blocks inside one container
- Dynamic / Runtime: how interactions happen over time
- Deployment / Infrastructure: where software runs and how nodes connect
3. Prefer omission over overload
Do not try to be comprehensive. Omit details that do not help the target audience answer the central question.
4. Every symbol must mean something
All boxes, colors, borders, arrows, icons, line styles, and group boundaries must have clear semantics.
If semantics are not obvious, add a legend.
5. Relationships must be explicit
Every important relationship should show:
- direction
- meaning
- where relevant, technology / protocol / interface type
Prefer unidirectional arrows. Avoid ambiguous double-headed arrows unless the user explicitly needs to emphasize two-way communication and you can label both directions clearly.
6. Text is not optional when ambiguity remains
Use short textual support when the diagram alone may be misread:
- assumptions
- element descriptions
- interface notes
- protocol / channel notes
- constraints
- risk / trust boundaries
7. Maintainability matters
Choose a diagram structure that can be updated without pain. Do not create visually impressive but brittle diagrams.
Keep the source editable and make assumptions visible.
8. Separate static structure from dynamic flow
A layered architecture diagram shows structure and dependency: vertical stacking where upper layers run on / reuse lower layers. It must NOT contain request-path arrows, numbered steps (①→②→③), or cross-layer "and then" edges — those belong to the sequence diagram.
If you are explaining a running system, produce the pair and cross-reference them ("static structure: see diagram A; one request's path: see diagram B"). Never merge the two views into one picture.
9. Legend and diagram must align in both directions
Everything the legend mentions must be visibly present in the diagram, and every distinct visual encoding in the diagram (line style, border, grouping label) must be covered by the legend. If the legend references layer identifiers (L1/L2/L3/L4), those identifiers must literally appear inside the diagram's group titles — not only in the surrounding prose.
Non-callers must not be drawn as callers. Instruction libraries, configuration data, plugin capabilities, and per-request injected payloads are not invokers — draw them as dashed side-attachments ("injected into", "mounted on") to the layer that consumes them, and keep the main call chain reserved for actual invokers.
Required inputs
Collect or infer the following before drawing:
- system name
- diagram goal
- target audience
- desired diagram type, if known
- system scope / boundary
- main actors, neighboring systems, services, stores, or infrastructure
- important relationships and data flows
- important constraints: security, trust boundary, latency, scale, ownership, deployment environment, compliance, etc.
- desired output format: Mermaid, PlantUML, Structurizr DSL, Excalidraw-style description, SVG plan, or natural-language diagram spec
If information is missing, do not stall unnecessarily.
Use this fallback order:
- infer from user context
- make minimal reasonable assumptions
- label assumptions explicitly
- ask only if the missing information blocks correctness in an important way
Default workflow
Step 1. Define the communication goal
Write one sentence in this form:
This diagram is for [audience] to understand [question / decision].
Examples:
- This diagram is for new developers to understand the major services and data stores of the budgeting app.
- This diagram is for reviewers to understand trust boundaries and external dependencies.
- This diagram is for a technical report to explain the progression from LLM to multi-agent orchestrator.
Step 2. Select the right deliverable(s)
First decide the deliverable set, then the type:
- Does the audience need to understand structure? -> at least one static diagram (context / container / component / deployment)
- Does the audience need to understand runtime behavior (request lifecycle, loop mechanics, event flow)? -> add a sequence diagram
- Explaining a whole system? -> default to the pair: one static layered diagram + one sequence diagram, cross-referencing each other
Then pick the static view via this mapping:
- Need to show system boundary and external actors -> System Context
- Need to show major services / apps / databases / queues -> Container
- Need to show internals of one service -> Component
- Need to show request flow / event flow / handoff -> Dynamic / Runtime (realize this as a sequence diagram, not as arrows crossing a layered block diagram)
- Need to show cloud resources / nodes / networks -> Deployment
- Need to show business inputs/outputs across boundaries -> Business Context / Data Flow flavored context
If the user says “architecture diagram” without specifying, default to:
- System Context, then
- Container
unless the request clearly points to deployment or runtime behavior.
Step 3. Determine scope and boundaries
Clearly identify:
- what is in scope
- what is out of scope
- external actors / systems
- trust boundaries, network boundaries, ownership boundaries, or team boundaries when relevant
For context diagrams, distinguish between:
- business context: who exchanges what with the system
- technical context: through which channels, protocols, or infrastructure the exchange happens
Step 4. List only the essential elements
Keep only elements necessary for the chosen level.
Good default counts:
- context diagram: roughly 4 to 9 external entities plus the system in scope
- container diagram: roughly 5 to 12 major internal elements
- component diagram: only the components needed to explain the chosen concern
If the element list is too long, split the output into multiple diagrams.
Step 5. Name elements precisely
Avoid vague names like:
- business logic
- service layer
- processing module
- external API
- data handler
Prefer names that tell the reader what the element is and does.
Examples:
- Auth Service
- Billing API
- Recommendation Worker
- PostgreSQL Orders DB
- User Browser
- Admin Backoffice
Also include short descriptions when possible.
Step 6. Add relationships deliberately
For each line, define:
- source
- destination
- direction
- relationship meaning
- optional protocol / transport / data type
Good labels:
- submits transaction
- reads account summary
- publishes expense-created event
- syncs profile via HTTPS
- stores receipts in S3
Bad labels:
- uses
- connects
- interacts
- talks to
Step 7. Add technology only where it helps
Include technology / protocol labels when they add clarity, such as:
- Flutter mobile app
- FastAPI backend
- PostgreSQL
- Redis cache
- WebSocket
- HTTPS/REST
- Kafka topic
Do not turn the diagram into a tool catalog.
Step 8. Arrange layout for scanability
Apply these layout rules:
- place the main subject near the visual center or obvious starting position
- keep flow consistent, usually left-to-right or top-to-bottom
- minimize crossing lines
- reroute connectors or duplicate symbols when necessary to avoid spaghetti
- align related elements
- cluster by domain, team, boundary, or lifecycle when useful
- reserve whitespace; do not compress everything into one dense block
Step 9. Add legend, title, and metadata
Every final diagram should have:
- title
- diagram type
- scope
- legend / notation key when needed
- version or last updated date when the diagram is meant to live beyond the conversation
Recommended title format:
[Diagram Type] for [System Name]
Examples:
- System Context for Budgeting App
- Container Diagram for AI Tutoring Platform
- Deployment Diagram for Multi-Agent Runtime
Step 10. Add short supporting text
After the diagram, include a short section with:
- purpose of the diagram
- key assumptions
- reading order if non-obvious
- omitted details
- 3 to 5 key insights or design notes
Step 11. Self-review before delivering
Run the checklist at the end of this file.
Step 12. Validate before delivering
Mechanically verify, ideally with a small script:
- Mermaid structure: every
subgraph has a matching end; every edge references a defined node; alt/else blocks have their end.
- Label width budget (CJK text does not auto-wrap): subgraph title ≤ ~23 CJK chars, node line ≤ ~22, edge label ≤ ~11. Split with
<br/>.
- Legend alignment: every legend claim appears in the diagram and vice versa.
- Doc integration (when embedding in docs): relative links resolve; any
file:line anchors cited in prose match the actual files.
Recommended output structure
When producing a diagram, use this structure unless the user asks for something else:
- Goal
- Assumptions
- Diagram type chosen
- Diagram source (Mermaid / PlantUML / Structurizr DSL / text spec)
- Short interpretation notes
- Review checklist result
Output quality bar
A strong output should satisfy all of the following:
- the reader can identify the system in scope within 3 seconds
- the reader can tell what each major box represents
- the reader can follow the main interaction path without guessing
- no important line is unlabeled when the relationship is non-obvious
- no visual encoding is decorative only
- the chosen level matches the user’s real question
- the diagram does not try to explain every possible detail
Common anti-patterns to avoid
Anti-pattern 1. Mixed abstraction soup
One drawing mixes users, services, classes, queues, server nodes, and SQL tables.
Fix: split into separate views.
Anti-pattern 2. Comprehensive but unreadable
Trying to include everything “for completeness”.
Fix: optimize for comprehension, not exhaustiveness.
Anti-pattern 3. Unexplained colors and shapes
Red boxes, blue boxes, dashed lines, and shaded groups with no legend.
Fix: remove non-semantic styling or explain it.
Anti-pattern 4. Generic labels
Names like module, processor, manager, engine, handler, middleware, or system without role clarity.
Fix: rename to concrete responsibilities.
Anti-pattern 5. Ambiguous arrows
Lines with no direction, no labels, or double-headed arrows hiding two different interactions.
Fix: use single-direction relations and clear labels.
Anti-pattern 6. Wrong diagram type
Using a deployment diagram to explain product context, or a component diagram to explain business partners.
Fix: choose the view that matches the question.
Anti-pattern 7. Over-decorated diagram
Using icons, gradients, logos, or color noise that add visual weight but no information.
Fix: prefer clean, functional visuals.
Anti-pattern 8. No boundary thinking
Forgetting trust boundaries, ownership boundaries, or external interfaces when they are central to the discussion.
Fix: draw and label the relevant boundaries.
Anti-pattern 9. Diagram without companion explanation
The image is shown with no assumptions, no context, and no explanation of what was intentionally omitted.
Fix: add a short textual note.
Anti-pattern 10. Diagram that cannot be maintained
The output is visually polished but difficult to edit, update, or version.
Fix: prefer source-first representations such as Mermaid, PlantUML, Structurizr DSL, or a clearly structured textual diagram spec.
Anti-pattern 11. Mixing static and dynamic in one picture
A layered block diagram with numbered request-path arrows (①→②→③) crossing the layers, loop-backs, and "then/returns" edge labels. Readers cannot tell whether vertical means dependency or time.
Fix: split into the deliverable pair — vertical-dependency architecture diagram + autonumbered sequence diagram — and cross-reference them. Keep temporal vocabulary out of the static diagram's labels.
Anti-pattern 12. Legend disconnected from the diagram
The legend references labels (L1–L4), colors, or line styles that do not appear in the diagram — or the diagram uses encodings the legend never explains. Worse: the legend narrates meta-information (file inventory, config tables) instead of teaching how to read the picture.
Fix: enforce two-way alignment (legend ⇄ diagram); put layer identifiers literally inside group titles; replace meta-dump legends with a short reading guide (reading order, key takeaway, deliberate omissions).
Heuristics for choosing what to omit
Omit an element if all of the following are true:
- it is not needed to answer the main question
- it does not change the main flow or boundary understanding
- it does not materially affect risk, ownership, or constraints
- removing it makes the diagram easier to parse
Keep an element if any of the following are true:
- it is part of the core user/system interaction
- it is a major store, service, queue, or external dependency
- it defines a boundary or architectural decision
- it explains a risk, bottleneck, protocol, or trust issue
Diagram-type guidance
System Context
Show:
- system in scope
- people / external systems
- major incoming/outgoing interactions
- optionally business inputs/outputs
Do not show:
- internal microservices
- class/module internals
- low-level deployment details
Use when:
- onboarding
- project overview
- stakeholder communication
- report introductions
Container Diagram
Show:
- major applications/services/workers/data stores inside the system
- how they communicate
- key protocols and technologies where useful
Do not show:
- detailed classes/functions
- all internal implementation details
Use when:
- engineering overview
- architecture review
- planning service boundaries
Component Diagram
Show:
- significant internal building blocks inside one container
- only the components needed for the chosen concern
Do not show:
- every class or utility
- cross-system details that belong in a context/container view
Use when:
- explaining one service
- reviewing internal decomposition
Dynamic / Runtime Diagram
Show:
- ordered interactions
- triggers, handoffs, events, calls, responses
Use when:
- explaining request lifecycle
- event-driven behavior
- agent orchestration / tool invocation / workflow execution
Realize this as a sequence diagram (see the pairing guide below), not as numbered arrows crossing a layered block diagram.
Deployment Diagram
Show:
- environments, nodes, networks, clusters, regions, devices, cloud resources
- where containers/services run
- infrastructure channels and boundaries
Use when:
- ops, infra, security, latency, availability, compliance discussions
The deliverable pair: layered architecture diagram + sequence diagram
When documenting a real system, the strongest default output is two diagrams that cross-reference each other:
- Static layered architecture diagram (flowchart, top-to-bottom): vertical = dependency direction, upper layers run on / reuse lower layers. Side-attach non-invokers (config/instruction libraries, plugin capability packs) with dashed "mounted on / injected into" edges. State the reading rule in one sentence under the diagram ("vertical means dependency; upper runs on lower").
- Dynamic sequence diagram: one concrete request or task traversing those same components over time, with
autonumber steps, alt/else for execution branches, and Note over for phase summaries.
Rules for the pair:
- The sequence diagram carries everything the static diagram deliberately excludes: numbered request steps (① SSE → ② instruction injected → ③ model API → ④ tool-call returns), loop-backs, and branching paths.
- Participants in the sequence diagram should map 1:1 to boxes in the static diagram (name them the same, optionally grouped by layer, e.g.
participant L1 as L1 · /api/llm/stream). A reader must be able to hop between the two diagrams without translation.
- Each diagram ends with a one-line pointer to the other ("static structure: §2 / one request's path: §7").
- Do not put temporal vocabulary ("then", "returns", step numbers) into the static diagram's edge labels; use dependency vocabulary ("runs on", "calls via SSE", "mounted on").
Sequence diagram mechanics that earn their keep:
autonumber — the step numbers ARE the request path narrativealt / else — execution branching (e.g. one tool call resolving differently on desktop vs browser, local vs remote execution)Note over A,B — phase summaries spanning participants ("model plans wiring, then submits for validation")loop — for retry / auto-continue cycles (e.g. tool output fed back, next round auto-triggered)
Codebase documentation mode: directory anchoring
When the diagram documents a real repository (architecture docs, onboarding), anchor every group to an actual path so the reader can navigate from diagram to code:
- Group title = real directory + one-phrase duty, e.g.
📁 src/express/ — HTTP entry layer. Keep titles short (see CJK width budget); put full duty sentences in the surrounding prose, never inside the diagram.
- Node = path: duty, first line the file or directory, following lines the responsibility:
routes/llm.ts<br/>POST /api/llm/stream<br/>SSE relay + billing.
- Merge, don't enumerate: collapse minor files into their directory node; note the merge in the legend ("minor files folded, not exhaustively listed"). A diagram that lists every file stops being a map and becomes a manifest.
- Every module claim in prose should carry a
file:line anchor so readers can verify against code; verify those anchors before delivering (Step 12).
- Distinguish edge semantics and say so in the legend: solid = runtime call (label with protocol / IPC channel), dashed = static dependency / injection / not-yet-wired, dashed border = external system. Consistency across all diagrams in the same document matters more than any single convention.
Handling business context vs technical context
When drawing a context-level view, decide whether the user needs:
Business context
Focus on:
- actors
- neighboring systems
- domain inputs/outputs
- who exchanges what with whom
Prefer labels that read like data or business interactions.
Technical context
Focus on:
- protocols
- channels
- networks
- hardware / runtime environment
- interface realization
Prefer labels such as HTTPS, gRPC, WebSocket, SMTP, Kafka, S3, VPN, browser, mobile app, batch file, webhook, etc.
If both are important, either:
- produce two diagrams, or
- keep one primary diagram and add a compact mapping note
Advice for agent / AI / LLM system diagrams
When the system involves LLMs, agents, tools, memory, orchestrators, or MCP-like capability layers, make sure to separate these concerns clearly:
- user-facing client / channel
- orchestrator / supervisor / runtime
- model provider(s)
- tool layer / MCP / external integrations
- memory / state / vector store / file system
- event bus / queue / workflow runtime
- safety / policy / approval boundary if relevant
Common mistake: collapsing “LLM”, “agent”, “orchestrator”, “memory”, and “tools” into one box called AI.
Do not do that.
Advice for diagrams in reports or presentations
When the output is for a report, deck, or public-facing explanation:
- optimize for narrative clarity first
- reduce text density inside shapes
- keep a small number of dominant visual paths
- make the title informative, not generic
- ensure the central message can be understood from a quick glance
