I spent a week creating a beautiful architecture diagram in Lucidchart when I joined my third company. Color-coded boxes, clean arrows, labeled data flows. By the time I presented it to the team, two services had been renamed and a new database had been added. The diagram was wrong before it was finished.
That experience taught me something I should have learned years earlier: hand-drawn architecture diagrams are a maintenance burden disguised as documentation. Diagrams need a maintainable source and an owner. Generated views and versioned, text-based diagrams can both help.
Manual diagrams fail for the same reason all static documentation fails: code changes faster than docs. But diagrams are worse than written docs because they're harder to update. Editing a paragraph takes 30 seconds. Rearranging boxes and arrows in a diagramming tool takes 30 minutes.
The result is predictable. Teams create diagrams during planning, maybe update them once after launch, and then abandon them. Six months later, a new hire finds the diagram, assumes it's accurate, and builds mental models on a foundation of lies.
Figure 1. Choose the view that answers the question you are investigating.
Not all visualizations are created equal. After experimenting with dozens of approaches, I've settled on four types that actually provide ongoing value.
# Install madge and Graphviz (Ubuntu example)npm install -g madgesudo apt-get install graphviz# Generate a dependency graph as SVGmadge --extensions ts,tsx --ts-config tsconfig.json --image dependency-graph.svg src/# Find circular dependenciesmadge --extensions ts,tsx --ts-config tsconfig.json --circular src/# Generate a graph for a specific modulemadge --extensions ts,tsx --ts-config tsconfig.json --image orders.svg src/orders/
Madge produces clean, readable graphs for projects up to about 200 modules. Beyond that, the graphs become spaghetti. For larger projects, filter by directory:
bash
# Only show dependencies within the orders modulemadge --extensions ts,tsx --ts-config tsconfig.json --image orders-internal.svg --exclude "^(?!orders/)" --basedir src src/orders/
For Go:
bash
# List module dependencies with the built-in Go commandgo mod graph# Convert that edge list to DOT with a separate tool before Graphviz rendering.
The C4 model (Context, Containers, Components, Code) by Simon Brown provides four zoom levels for architecture visualization. The key insight is that you need different diagrams for different audiences.[2]
Level
Audience
Shows
Update Frequency
Context
Executives, new hires
System + external actors
Quarterly
Container
Architects, DevOps
Services, databases, queues
Monthly
Component
Developers
Modules within a service
As needed
Code
Developers
Classes/functions
Never (use IDE)
For C4 diagrams, I use Structurizr DSL because it's code-based and lives in the repo:
workspace {
model {
user = person "Customer"
system = softwareSystem "E-Commerce Platform" {
webapp = container "Web App" "Next.js" "TypeScript"
api = container "API Server" "Express" "TypeScript"
db = container "Database" "" "PostgreSQL"
cache = container "Cache" "" "Redis"
queue = container "Message Queue" "" "RabbitMQ"
}
user -> webapp "Browses products, places orders"
webapp -> api "API calls" "HTTPS/JSON"
api -> db "Reads/writes data" "SQL"
api -> cache "Caches sessions, product data"
api -> queue "Publishes order events"
}
views {
container system {
include *
autolayout lr
}
}
}
This DSL file lives in docs/architecture/workspace.dsl. Use Structurizr local to view the DSL workspace and adjust diagram layout. It is the current free, open-source equivalent of Structurizr Lite. Because it's code, it goes through PR review when updated.[3]
Some visualizations need human judgment. Data flow diagrams show how data moves through the system: where it enters, how it transforms, where it persists. These change less frequently than code structure because data flows tend to be stable even as implementation details change.
I use Mermaid for these because it's text-based, renders in GitHub markdown, and is easy to update:[4]
graph LR
A[Client Browser] -->|POST /api/orders| B[API Gateway]
B -->|Validate + Auth| C[Order Service]
C -->|Check stock| D[Inventory Service]
C -->|Create order| E[(Orders DB)]
C -->|Publish event| F[Message Queue]
F -->|order.created| G[Payment Service]
F -->|order.created| H[Notification Service]
G -->|Payment result| E
These visualize which parts of your codebase get the most attention. Built from git history, they show file size as bubble size and change frequency as color intensity.
bash
# Count file appearances in Git historygit log --format=format: --name-only --since="6 months ago" | \ sed '/^$/d' | sort | uniq -c | sort -rn > churn.txt# Combine with LOC counts for a treemap visualizationcloc --by-file --csv src/ > loc.csv
Tools like CodeScene generate these automatically and provide interactive treemaps. For a free alternative, you can feed the data into D3.js or use the git-of-theseus tool.
# My Contrarian Take: Most Architecture Diagrams Should Be Ugly
I was wrong for years about diagram aesthetics. I spent hours making diagrams pretty: consistent colors, aligned boxes, curved arrows. Beautiful diagrams. Useless diagrams, because they were too expensive to update.
The diagrams that actually get maintained are the ugly ones. A Mermaid diagram in a markdown file. A text-based dependency graph. A whiteboard photo saved to the repo. These get updated because updating them takes 5 minutes, not 50.
Optimize for accuracy and maintainability, not beauty. A correct ugly diagram is worth infinitely more than a beautiful outdated one.
This regenerates the dependency graph on matching changes. Review unresolved imports and check repository branch rules before allowing the workflow to push generated files.
Start with one auto-generated dependency graph and one hand-drawn C4 Container diagram. That's enough for most teams. Add more visualizations only when you have a specific question that existing visualizations can't answer.
The goal isn't to create diagrams. It's to make the codebase understandable. Sometimes the best visualization is a three-line Mermaid diagram in a README. Sometimes it's a generated SVG in CI. Match the tool to the need.
Frequently asked questions
Which architecture diagram should I create first?
Start with a system boundary view and a dependency graph for the area you are changing. Together they show the outside connections and the internal imports, giving you a basis for asking more detailed questions.
Can dependency graphs explain runtime behaviour?
Import graphs show structural relationships in source code. Use a separate data-flow view to explain requests, queues and persistence, and check the running system when the diagram needs to describe actual behaviour.
What does Madge need to generate TypeScript diagrams?
Install Graphviz for image output and configure the TypeScript extensions and project configuration. Run Madge against the directory or entry point you intend to inspect and review warnings about unresolved imports.
How can architecture diagrams stay current?
Keep diagram definitions or generation commands in the repository and review them with code changes. A CI job can generate diagrams, while the team checks that the selected view still answers its intended question.
Architecture fitness functions are automated tests for your system's structural properties. Here's how to implement the 5 most impactful ones and integrate them into your CI pipeline.
Use Git history analysis to find frequently changed files, co-change patterns and contributor concentration. Run reproducible queries and inspect their limits.
Choose static analysis tools for types, security data flow and architecture rules. Follow a staged setup and tune findings against your team’s actual defects.
No single person can hold a large codebase in their head. A knowledge graph externalizes understanding into a queryable structure. Here's the 4-week playbook to build one.
Choose code search tools for text, symbols and cross-repository exploration. Use ripgrep, GitHub and Sourcegraph queries to find code and related changes.