Circles and Arrows Design

"The best way to have a good idea is to have lots of ideas." — Linus Pauling, as quoted in The Pragmatic Programmer

This repository demonstrates system design using diagrams and clear documentation, following the "Circles and Arrows" principle from The Pragmatic Programmer. The goal is to create useful, maintainable diagrams that communicate system architecture and data relationships effectively—without over-engineering.

What is "Circles and Arrows"?

In The Pragmatic Programmer (Hunt & Thomas), the authors emphasize that good design documentation uses simple, clear diagrams—"circles and arrows"—rather than overly complex UML diagrams that become maintenance burdens. The focus is on:

• Clarity over completeness: Show what matters, not every detail
• Maintainability: Diagrams should be easy to update as the system evolves
• Communication: Diagrams should help teams understand the system quickly

Repository Structure

.
├── diagrams/           # Diagram source files
│   ├── architecture.mmd    # System architecture diagram
│   └── data-model.mmd      # Entity-relationship diagram
├── docs/              # Documentation
│   ├── ARCHITECTURE.md    # System architecture documentation
│   └── DATA_MODEL.md      # Data model documentation
└── README.md          # This file

Sample Application

This repository uses a sample e-commerce platform to demonstrate:

• Architecture Diagram: Microservices-based system with API gateway, services, databases, and external integrations
• Data Model: Entity-relationship diagram showing users, products, orders, payments, and their relationships

The application is intentionally simplified to focus on diagramming and documentation practices rather than implementation details.

Viewing Diagrams

Option 1: GitHub/GitLab (Recommended)

If you push this repository to GitHub or GitLab, the Mermaid diagrams will render automatically in markdown files. Simply view the files in the docs/ directory.

Option 2: VS Code

1. Install the Markdown Preview Mermaid Support extension
2. Open any .md file in the docs/ directory
3. Use the Markdown preview (Cmd+Shift+V on Mac, Ctrl+Shift+V on Windows/Linux)

Option 3: Online Mermaid Editor

1. Visit Mermaid Live Editor
2. Copy the contents of any .mmd file from diagrams/
3. Paste into the editor to view and edit

Option 4: Command Line (with Mermaid CLI)

# Install Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# Generate PNG from diagram
mmdc -i diagrams/architecture.mmd -o diagrams/architecture.png

# Generate SVG (scalable)
mmdc -i diagrams/architecture.mmd -o diagrams/architecture.svg

Option 5: Documentation Sites

Many documentation platforms support Mermaid:

• GitBook: Native Mermaid support
• Notion: Supports Mermaid code blocks
• Confluence: With Mermaid plugin
• Docusaurus: Built-in Mermaid support

Editing Diagrams

Using Mermaid Syntax

Diagrams are written in Mermaid syntax, which is:

• Text-based: Easy to version control and diff
• Human-readable: Can be understood without rendering
• Widely supported: Works in many markdown renderers

Quick Reference

Graph/Flowchart:

graph TB
    A[Node A] --> B[Node B]
    B --> C[Node C]

Loading

ER Diagram:

erDiagram
    USER ||--o{ ORDER : places
    USER {
        uuid id PK
        string email
    }

Loading

Sequence Diagram:

sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response

Loading

See the Mermaid documentation for complete syntax.

Best Practices

1. Keep it simple: Focus on the essential relationships and flows
2. Use meaningful names: Node and entity names should be self-explanatory
3. Group related components: Use subgraphs to organize related elements
4. Add styling sparingly: Use colors and styles to highlight important parts, not everything
5. Update with code: When the system changes, update the diagrams

Documentation Files

• ARCHITECTURE.md: Explains the system architecture, components, and key flows
• DATA_MODEL.md: Describes entities, relationships, and design decisions

Why This Approach?

1. Version Control Friendly: Text-based diagrams can be diffed, reviewed, and merged like code
2. Low Maintenance: Simple diagrams are easier to keep up-to-date
3. Accessible: Works in many tools without special software
4. Collaborative: Team members can edit diagrams without proprietary tools
5. Documentation as Code: Diagrams live alongside code, making them easier to maintain

Further Reading

• The Pragmatic Programmer by Andrew Hunt and David Thomas
• Mermaid Documentation
• PlantUML (alternative diagramming tool)
• C4 Model (architecture diagramming methodology)

License

This repository is provided as an example and reference. Feel free to use and adapt it for your own projects.

---

Remember: The best diagram is one that helps your team understand the system. If a diagram becomes too complex to maintain, simplify it. If it's not being used, question whether it's needed at all.