Diagram Design: FOSS Tools for Effective Tech Diagrams

Diagram Design: FOSS Tools for Effective Tech Diagrams

Diagram Design refers to the approach and tools for creating clear, precise, and maintainable technical diagrams, often using ‘as Code‘ methodologies with FOSS (Free and Open Source Software) like PlantUML, Mermaid, and the Python diagrams library. This automates the generation and version control of visual representations for complex systems.

How many times have you spent hours dragging shapes and connectors in a proprietary graphic tool, only to redo everything after a minor architectural change? I’ve seen teams halt entire days to update a network diagram that should have been ready in an hour. This is not only inefficient but creates a discrepancy between operational reality and documentation—a huge risk in enterprise environments with hundreds of VMs and services. The Diagram Design approach with FOSS tools solves this problem, allowing you to generate and maintain technical diagrams quickly, accurately, and in a version-controlled manner. It transforms a tedious task into an automated process that always reflects the current state of the infrastructure.

Tested on: Ubuntu 24.04 LTS · PlantUML 1.2024.6 · Mermaid CLI 10.9.1 · Python 3.10 with diagrams 0.23.1 · August 2026

Prerequisites / Test Environment

To follow this guide, you will need a Linux environment (Ubuntu 24.04 LTS is recommended) with terminal access. PlantUML requires Java Runtime Environment (JRE). Mermaid needs Node.js and npm. The diagrams library requires Python 3 and pip. All tools are easily installable via their respective package managers.

# Install JRE for PlantUML
sudo apt update && sudo apt install -y default-jre

# Install Node.js and npm for Mermaid CLI
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g @mermaid-js/mermaid-cli

# Install Python and pip for diagrams
sudo apt install -y python3 python3-pip
pip install diagrams

1. PlantUML: UML Diagrams from Text

PlantUML is a powerful tool for generating UML (Unified Modeling Language) diagrams from a simple text description. It is particularly useful for sequence, class, state, and component diagrams, and is widely supported in IDEs, Wikis (like Confluence), and Markdown documentation via plugins. Its syntax is intuitive, allowing you to focus on content rather than formatting.

To use it, you create a .puml file with the diagram description and then convert it into an image (PNG, SVG) using the PlantUML compiler.

@startuml
actor User
participant "Web Application" as Web
participant "Backend API" as API
database "SQL Database" as DB

User -> Web: Requests Page
Web -> API: Loads User Data
API -> DB: SELECT * FROM Users WHERE id=X
DB --> API: User Data
API --> Web: User Data JSON
Web --> User: Displays Page
@enduml

To generate the image, you can use the command line if you have the PlantUML JAR installed, or an IDE with the dedicated plugin. Read also: Technical Documentation: Integrate Diagrams with PlantUML in Markdown

2. Mermaid: Diagrams for Web and Markdown

Mermaid offers a Markdown-like syntax to create flowcharts, UML diagrams, Gantt charts, and other types directly within web documents. It is natively supported by platforms like GitHub, GitLab, and Azure DevOps, making it ideal for documentation integrated into code repositories. Its simplicity and ability to be rendered directly in the browser make it a versatile tool.

Here is an example of a Mermaid flowchart:

graph TD
    A[Start] --> B{Decision?}
    B -- Yes --> C[Action 1]
    B -- No --> D[Action 2]
    C --> E[End]
    D --> E

You can include this block directly in an .md file on GitHub, and it will be rendered automatically. To generate an image from the command line, use mmdc:

mmdc -i input.mmd -o output.png -t dark

This command takes the input.mmd file and generates output.png with a dark theme. Read also: Proxmox VE: Complete Installation & Configuration Guide 2026

3. Diagrams as Code: Architectures with Python

The Python diagrams library allows you to draw system architectures (cloud, on-premise, container) using Python code. It is based on Graphviz and offers a wide range of icons for AWS, GCP, Azure, Kubernetes, On-Premise services, and many others. This approach is excellent for defining complex architectures and generating diagrams that can be versioned alongside infrastructure as code (IaC).

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("Simple Web Architecture", show=False):
    ELB("Load Balancer") >> EC2("Web Server") >> RDS("Database")

This Python script, once executed, will generate a PNG (or SVG) file representing the architecture. The output can be integrated into CI/CD pipelines to ensure diagrams are always up-to-date with infrastructure changes. Read also: Ansible: Simple and Powerful IT Automation — A Definitive Guide

Common Errors and Troubleshooting

• PlantUML not generating images: Check your Java installation (java -version). Ensure the .puml file is well-formed and has no syntax errors. Common errors include actor or participant not being defined correctly.
• Mermaid not rendering on GitHub: Verify the syntax. GitHub is sensitive to spaces and special characters. Use an editor that supports Mermaid preview for debugging.
• diagrams not working: Make sure you have Graphviz installed (sudo apt install graphviz) and that it is in your PATH. Also, check the Python library installation (pip show diagrams). Common errors are related to missing icons or Graphviz dependencies.

FAQ — Frequently Asked Questions

Is it possible to integrate these tools into a CI/CD pipeline?

Yes, absolutely. The ‘as Code’ nature of PlantUML, Mermaid, and diagrams makes them perfect for integration. You can add steps in your Jenkins, GitLab CI, or GitHub Actions pipeline to compile .puml or .mmd files, or execute Python scripts to generate diagram images, which can then be published as part of your documentation.

What is the main advantage over a traditional graphical tool?

The main advantage is version control and automation. With a graphical tool, every change requires manual intervention, and versioning is complicated (binary diffs). With the ‘as Code’ approach, diagrams are text files that can be versioned with Git, allowing you to track changes, collaborate, and integrate generation into automated processes, ensuring documentation always aligns with the actual infrastructure.

Can I use these tools for non-technical diagrams?

Certainly. While very popular in technical fields, their flexibility allows for creating flowcharts for business processes, organizational charts, Gantt charts for project management, and many other types of visual representations, making them useful for non-IT teams seeking an efficient way to document workflows.

Which tool should I choose for my project?

It depends on the context. For detailed UML diagrams and Wiki integration, PlantUML is excellent. For web documentation and simple Markdown, Mermaid is the best choice. For complex architectures and generating diagrams directly from infrastructure code, the Python diagrams library is unsurpassed. Often, combinations of the three are used depending on the specific diagramming needs.

Conclusions with Operational Takeaways

Adopting a Diagram Design approach with FOSS tools like PlantUML, Mermaid, and the Python diagrams library is a strategic move for any IT team. It drastically reduces the time spent creating and updating diagrams and improves documentation quality and accuracy. Version control via Git and integration into CI/CD pipelines ensure your diagrams are always up-to-date, reflecting the reality of your infrastructure. Start experimenting with these tools: the learning curve is short, and the long-term benefits for your team’s productivity and communication clarity are significant.

Sources

• PlantUML Official Website
• Mermaid Official Website
• Diagrams Python Library Documentation

Updated: August 2026