Why use architecture diagram Skills
- Purpose: convert relationships scattered across docs, code and infra definitions into discussion-ready views for design reviews and operations.
- Key decisions: first identify the audience (executives, developers, ops), the core question (system boundary, request path, deployment topology), and the output format (Mermaid text for versioning, draw.io for interactive editing, SVG/PNG for static delivery).
Typical tasks and recommended outputs (short guide)
- Map services and dependencies (from a codebase): use a Skill that reads source or service manifests and exports C4/component views; prefer Mermaid or draw.io so diagrams remain editable.
- Explain request paths or business flows: use Skills that support sequence diagrams, flowcharts or data flows. Mermaid is convenient for text-based workflows; SVG works for embedded images.
- Review cloud resources and network boundaries: use a Skill that parses cloud resources or IaC and clearly shows subnets, resource groups, NSGs and trust boundaries. Ensure exported artifacts are editable and sensitive data is removed.
Worked example: e-commerce order flow (small system)
Goal: produce two diagrams for two audiences: 1) a sequence chart of the order submission (for developers); 2) a deployment topology showing network boundaries and subnets (for ops/security). System components (simplified):
- API Gateway
- Order Service
- Payment Service (third-party)
- Inventory Service
- MySQL (orders DB)
- Redis (session/cache)
- Azure subnets: AppSubnet, DBSubnet
Deliverables:
- Mermaid sequence diagram describing the order request path
- draw.io editable deployment topology showing subnets and restricted DB access
Steps (generic, applies to most Skills): 1) Prepare inputs - Service README or API docs listing responsibilities and external dependencies - Code repo artifacts (package manifests, Dockerfiles, compose or k8s manifests) - IaC manifests or a hand-curated resource inventory if IaC is unavailable 2) Clarify audience and the single question each diagram must answer 3) Choose Skill output formats per view - Request flow: Mermaid sequence for easy diffs and review - Deployment topology: draw.io editable file for ops to adjust visually 4) Run the Skill (abstract flow—follow the specific Skill's instructions) - Format inputs according to the Skill's requirements - Set the desired output format (Mermaid / draw.io) - Start with a small scope (e.g., Order ↔ Payment ↔ DB) to validate mapping 5) Review generated diagrams - Ask service owners to confirm components, directions and missed dependencies - Perform a security check on the deployment diagram to remove secrets or internal identifiers 6) Export and store source artifacts - Save Mermaid source or draw.io files in version control for future updates
Suggested example content (illustrative)
- Mermaid sequence (pseudo-text):
- User -> API Gateway -> Order Service -> Inventory Service - Order Service -> Payment Service (external) - Order Service -> MySQL write order - Inventory Service -> MySQL update stock
- Deployment topology notes:
- AppSubnet: API Gateway, Order, Inventory, Redis - DBSubnet: MySQL (restricted access) - NSG rules: AppSubnet -> DBSubnet TCP:3306 allowed only from Order/Inventory
Acceptance checklist (manual verification required)
- Consistency
- Are component responsibilities shown (short phrases) rather than only names? - Are arrow directions and protocols labeled (HTTP/gRPC/queue) where helpful?
- Completeness
- Are runtime dependencies (third-party APIs, manual steps, external queues) included? - Has the diagram been checked against code and IaC for mismatches in service count, ports or environments?
- Security and privacy
- Have secrets, account IDs, and private addresses been removed or redacted from outputs?
- Maintainability
- Are editable source files (Mermaid/draw.io) saved and under version control?
- Readability
- If the diagram is complex, has it been split into multiple focused views (context/container/component/deployment)?
Common limitations and caveats
- Static analysis limits: automatic extraction from code or IaC can miss runtime wiring, external services, manual processes and failure modes; human review is essential.
- Overloading a single diagram: putting every node and layer on one canvas reduces clarity—split by concern and audience.
- Output format constraints: not every Skill supports every export format; confirm supported formats up front.
- Sensitive information: cloud topology diagrams must be scrubbed of keys, real IPs and account identifiers before sharing.
Practical recommendations
- Iterate: run the Skill on a small subset, validate with owners, then expand scope and permissions as needed.
- Audience-specific views: produce different diagrams for executives (high-level context), developers (container/component) and ops (deployment/network).
- Keep editable sources in version control and tie diagram updates to architecture or deployment changes.
Summary
Skills that generate architecture diagrams speed up creating draft visuals, but their outputs are starting points—not authoritative maps. Define the audience and question first, preserve editable sources, and verify generated diagrams against owners, code and IaC. The recommended workflow is: generate → review → revise → commit, so diagrams remain accurate as systems evolve.