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