System Diagram Generator

Generate clear, accurate visual representations of system structure using text-based diagram formats.

Quick Start

When a user requests a system diagram:

1. Understand the system: Ask clarifying questions about components, relationships, and scope
2. Choose the format: Select based on user preference or context (default to Mermaid for versatility)
3. Select diagram type: Match the visualization to the information being conveyed
4. Generate the diagram: Create the diagram code with clear labels and structure
5. Provide context: Include a brief explanation of what the diagram shows

Format Selection

Mermaid (Default)

Use for most cases - renders in Markdown, GitHub, GitLab, and many documentation tools.

Best for:

• Quick visualizations
• Documentation in Markdown files
• GitHub/GitLab README files
• General-purpose diagrams

See: mermaid-patterns.md for examples

PlantUML

Use when detailed UML diagrams are needed or when working with Java/enterprise systems.

Best for:

• Detailed UML diagrams
• C4 architecture models
• Complex component relationships
• Enterprise documentation

See: plantuml-patterns.md for examples

Graphviz/DOT

Use for complex network topologies or when fine-grained layout control is needed.

Best for:

• Network diagrams
• Complex hierarchies
• Graph structures
• Custom layout requirements

See: graphviz-patterns.md for examples

Diagram Types

Architecture Diagrams

Show system components, services, databases, and their relationships.

Use when:

• Explaining system structure
• Documenting microservices
• Showing component dependencies
• Illustrating system boundaries

Key elements:

• Services/components (boxes)
• Databases (cylinders)
• External systems
• Communication protocols
• Data stores

Data Flow Diagrams

Illustrate how data moves through the system.

Use when:

• Explaining data processing pipelines
• Documenting ETL processes
• Showing transformation steps
• Illustrating validation flows

Key elements:

• Data sources
• Processing steps
• Transformations
• Data stores
• Outputs

Deployment Diagrams

Show infrastructure, servers, containers, and deployment topology.

Use when:

• Documenting cloud infrastructure
• Explaining deployment architecture
• Showing network topology
• Illustrating container orchestration

Key elements:

• Cloud providers/regions
• Networks/subnets
• Servers/containers
• Load balancers
• Databases and caches

Sequence Diagrams

Visualize API calls, user interactions, and process flows over time.

Use when:

• Documenting API interactions
• Explaining authentication flows
• Showing request/response cycles
• Illustrating multi-step processes

Key elements:

• Actors/participants
• Messages/calls
• Time sequence (top to bottom)
• Return values
• Conditional logic

Best Practices

Clarity

• Use descriptive, meaningful names for all components
• Keep diagrams focused on one aspect of the system
• Avoid overcrowding - split complex systems into multiple diagrams
• Use consistent naming conventions

Structure

• Group related components using subgraphs/clusters
• Show clear directional flow (left-to-right or top-to-bottom)
• Use appropriate shapes for different component types
• Include relevant protocols and technologies

Context

• Add a title or caption explaining what the diagram shows
• Include legends for non-obvious symbols or colors
• Provide brief explanations of key components
• Note any assumptions or simplifications

Format-Specific

• Mermaid: Use standard graph types (flowchart, sequence, C4)
• PlantUML: Leverage UML stereotypes and C4 includes
• Graphviz: Use clusters for grouping and rankdir for layout

Workflow

1. Gather requirements

   • What system or process needs visualization?
   • What level of detail is needed?
   • Who is the audience?
   • Any format preferences?

2. Choose format and type

   • Select diagram format (Mermaid/PlantUML/Graphviz)
   • Select diagram type (architecture/data flow/deployment/sequence)
   • Load relevant reference file if needed

3. Create diagram

   • Define all components/nodes
   • Establish relationships/edges
   • Add grouping/structure
   • Include labels and protocols

4. Validate and refine

   • Ensure all components are labeled
   • Verify relationships are clear
   • Check for visual balance
   • Add explanatory text

5. Deliver

   • Provide the diagram code in a code block
   • Include brief explanation
   • Suggest improvements or variations if relevant

Example Usage Patterns

User: "Show me the architecture of our authentication system" → Create Mermaid architecture diagram showing auth components

User: "Diagram the data flow for user registration" → Create Mermaid flowchart showing registration data flow

User: "Visualize our AWS deployment" → Create Mermaid or Graphviz deployment diagram with AWS infrastructure

User: "Show the sequence of API calls for checkout" → Create Mermaid sequence diagram showing checkout flow

User: "I need a detailed UML component diagram" → Create PlantUML component diagram with stereotypes

User: "Map out our network topology" → Create Graphviz network diagram with clusters