How mingrammer/diagrams works
This repository is a Python library for “diagram as code,” not an application backend. The core product is the diagrams package, which exposes Python objects users import in their own scripts to assemble architecture diagrams and render them through Graphviz.
1. Primary runtime boundary
- The main runtime is a Python package installed by users.
- User code imports classes from diagrams.*, builds a graph of nodes and edges, and the library emits Graphviz/DOT output for rendering.
- The repository itself does not manage cloud resources or call provider APIs; it only models infrastructure visually.
2. Core library layer
- The diagrams/ directory is the main codebase.
- diagrams/base, diagrams/c4, and diagrams/custom provide the foundational abstractions and special diagram styles.
- diagrams/cli.py provides a command-line interface around diagram generation/inspection.
3. Provider and domain namespaces
- Most of the package is organized by provider or domain: aws, azure, gcp, k8s, onprem, saas, programming, generic, openstack, elastic, firebase, ibm, oci, outscale, digitalocean, alibabacloud, and gis.
- Each namespace is further split into functional groups such as compute, database, network, storage, security, analytics, and management.
- This is the main surface area users interact with when authoring diagrams.
4. Icon/resource layer
- The resources/ tree stores the source image assets for every node icon.
- The mirrored directory structure between resources/ and diagrams/ is intentional: resource categories map to Python modules that expose typed node classes.
- website/static/img/resources/ contains the same assets for documentation rendering on the website.
5. Code generation pipeline
- scripts/generate.py and scripts/resource.py indicate that provider modules are generated or synchronized from resource definitions rather than hand-maintained entirely.
- templates/ contains Jinja-like module and API doc templates used to emit consistent Python modules and documentation.
- This generation boundary is important: icons are the source material, templates/scripts turn them into importable classes.
6. Rendering flow
- The library depends on Graphviz for layout/rendering.
- The likely flow is: user-defined Python diagram code → library builds a graph model → Graphviz renders the diagram to an image/PDF/SVG output.
- The repository ships the model layer and convenience APIs, but rendering is delegated to the external Graphviz toolchain.
7. CLI and automation
- diagrams/cli.py and the supporting scripts suggest the package can be used both as a library and through command-line workflows.
- The CLI is part of the same Python package boundary, so it operates on the same core diagram model rather than a separate service.
8. Documentation subsystem
- docs/ contains the technical docs for installation, examples, and node catalogs.
- website/ is a separate static documentation site built with JavaScript tooling, likely used for publishing the public docs and resource browser.
- This is a documentation-only boundary; it does not participate in diagram generation at runtime.
9. Testing and quality gates
- tests/ covers core behavior such as C4 support, CLI behavior, and diagram construction.
- GitHub Actions workflows run tests, pre-commit checks, and CodeQL analysis.
- These are repository maintenance boundaries, not product runtime components.
10. Packaging and developer experience
- pyproject.toml, .pre-commit-config.yaml, .isort.cfg, and config.py define packaging and formatting conventions.
- .devcontainer/ and docker/dev/ provide reproducible developer environments.
- These pieces support contributors and CI rather than end users directly.
11. External dependencies that matter architecturally
- Graphviz is the key external runtime dependency because it performs layout/rendering.
- Python 3.9+ is the package runtime baseline.
- The website adds a Node/JS build path, but only for docs publishing.
12. Overall system shape
- The repository has a clear three-part structure: source icons, generated/importable Python node classes, and docs/site assets.
- The main data flow is asset cataloging → code generation → user diagram authoring → Graphviz rendering.
- The dominant boundary is between the library’s diagram model and the external renderer, with a separate boundary for documentation publishing.
Main entry points: generate.py Generator · base/__init__.py Base model · diagrams/__init__.py diagrams · tests Tests
Components 24
Python library
Importable diagram model and node catalog used by end users.
- diagrams · Main Python package boundary for the library.
diagrams/__init__.py - Base model · Foundational diagram and node abstractions.
diagrams/base/__init__.py - C4 support · Specialized C4 diagram abstractions.
diagrams/c4/__init__.py - Custom nodes · Custom diagram node support.
diagrams/custom/__init__.py - CLI · Command-line entrypoint for diagram workflows.
diagrams/cli.py
Provider catalog
Domain namespaces that define the node classes users import in diagram scripts.
- AWS · AWS node catalog split into functional categories.
diagrams/aws/__init__.py - Azure · Azure node catalog split into functional categories.
diagrams/azure/__init__.py - GCP · Google Cloud node catalog split into functional categories.
diagrams/gcp/__init__.py - K8s · Kubernetes-oriented node catalog.
diagrams/k8s/__init__.py - On-prem · Self-hosted and infrastructure software catalog.
diagrams/onprem/__init__.py - SaaS · Software-as-a-service catalog.
diagrams/saas/__init__.py - Generic · Fallback generic infrastructure nodes.
diagrams/generic/__init__.py - OpenStack · OpenStack service catalog.
diagrams/openstack/__init__.py - GIS · Geospatial and tooling-oriented catalog.
diagrams/gis/__init__.py
Generation pipeline
Scripts and templates that synchronize resources into Python modules and docs.
- Resources · Source image assets mirrored to the Python module structure.
resources - Generator · Synchronizes resources into importable modules.
scripts/generate.py - Resource tools · Resource handling and catalog support for code generation.
scripts/resource.py - Templates · Module and API doc templates for generated output.
templates
Documentation
Docs content and the public website for examples and resource browsing.
Repo ops
Testing, CI, packaging, and development environment support.
Connections 33
- diagrams → Base model: defines · Core package exposes the diagram model layer.
- diagrams → C4 support: extends · Package includes a specialized C4 boundary.
- diagrams → Custom nodes: extends · Package includes custom node support.
- diagrams → CLI: offers · The library also ships a CLI entrypoint.
- Base model → AWS: used by · Core abstractions back provider namespaces.
- Base model → Azure: used by · Core abstractions back provider namespaces.
- Base model → GCP: used by · Core abstractions back provider namespaces.
- Base model → K8s: used by · Core abstractions back provider namespaces.
- Base model → On-prem: used by · Core abstractions back provider namespaces.
- Base model → SaaS: used by · Core abstractions back provider namespaces.
- Base model → Generic: used by · Core abstractions back provider namespaces.
- Base model → OpenStack: used by · Core abstractions back provider namespaces.
- Base model → GIS: used by · Core abstractions back provider namespaces.
- Resources → Generator: feeds · Icon assets are the source material for generated modules.
- Resource tools → Generator: supports · Resource logic assists generation and synchronization.
- Templates → Generator: templates · Generation uses templates for modules and docs.
- Generator → AWS: emits · Generated provider modules mirror resource categories.
- Generator → Azure: emits · Generated provider modules mirror resource categories.
- Generator → GCP: emits · Generated provider modules mirror resource categories.
- Generator → K8s: emits · Generated provider modules mirror resource categories.
- Generator → On-prem: emits · Generated provider modules mirror resource categories.
- Generator → SaaS: emits · Generated provider modules mirror resource categories.
- Generator → Generic: emits · Generated provider modules mirror resource categories.
- Generator → OpenStack: emits · Generated provider modules mirror resource categories.
- Generator → GIS: emits · Generated provider modules mirror resource categories.
- Docs → Website: publishes · Docs content is surfaced through the public website.
- Website → Resources: mirrors · Website hosts the same resource images for browsing.
- Tests → Base model: covers · Tests exercise diagram construction behavior.
- Tests → CLI: covers · Tests exercise the CLI boundary.
- Tests → C4 support: covers · Tests cover specialized C4 support.
- CI → Tests: runs · CI executes the test suite and checks.
- CI → Packaging: checks · CI validates formatting and quality gates.
- Dev env → Packaging: supports · Dev container provides reproducible contributor setup.