majiayu000 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:
- Understand the system: Ask clarifying questions about components, relationships, and scope
- Choose the format: Select based on user preference or context (default to Mermaid for versatility)
- Select diagram type: Match the visualization to the information being conveyed
- Generate the diagram: Create the diagram code with clear labels and structure
- 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
Gather requirements
- What system or process needs visualization?
- What level of detail is needed?
- Who is the audience?
- Any format preferences?
Choose format and type
- Select diagram format (Mermaid/PlantUML/Graphviz)
- Select diagram type (architecture/data flow/deployment/sequence)
- Load relevant reference file if needed
Create diagram
- Define all components/nodes
- Establish relationships/edges
- Add grouping/structure
- Include labels and protocols
Validate and refine
- Ensure all components are labeled
- Verify relationships are clear
- Check for visual balance
- Add explanatory text
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