architecture-diagram

Architecture Diagram Generator

When to use this skill

• When the user asks for an architecture diagram, system diagram, or component visualization.
• When updating READMEs that would benefit from visual architecture documentation.
• When comparing architectural alternatives visually (like the telemetry-architecture-comparison pattern).
• When the user wants to visualize data flow, package dependencies, or tech stack layers.

What this skill does

Generates publication-quality PNG architecture diagrams using Python + matplotlib. Diagrams use a consistent visual language: colored rounded boxes for components, styled arrows for data flow, dashed boundaries for service groups, and score badges for comparisons.

Implementation

Step 1: Identify the diagram type

Determine which diagram pattern fits the request:

Pattern	When to use	Example
High-level architecture	Full system overview with all components	high-level-architecture.png
Request/event flow	Show how data moves through a pipeline	server-request-flow.png
Package dependencies	Show import/dependency relationships	package-dependencies.png
Event flow	Show event sourcing or pub/sub patterns	orchestration-event-flow.png
Tech stack	Layered technology overview	tech-stack.png
Architecture comparison	Compare N alternatives with scores	telemetry-style comparison grid

Step 2: Use or extend the generator script

The diagram generator lives at scripts/generate-architecture-diagrams.py. It provides reusable primitives:

from generate_architecture_diagrams import (
    draw_box,      # Rounded colored rectangle with label + sublabel
    draw_arrow,    # Styled arrow with optional label and curve
    draw_boundary, # Dashed service/group boundary
    draw_badge,    # Colored score circle
    new_fig,       # Create a new figure with standard theme
    save,          # Save to assets/diagrams/
    THEME,         # Consistent color palette
    Box, Arrow,    # Dataclasses for components
)