# Understanding diagrams

Copy as Markdown[View as Markdown](/docs/development/guides/diagrams/introduction.md)

***

**Added in** `eventcatalog@3.3.0`

EventCatalog automatically generates architecture diagrams based on your resources and how they relate to each other. These auto-generated visualizations help you understand your system's structure.

**But what about your own diagrams?**

Many teams have existing architecture diagrams - whether they're Mermaid flowcharts, PlantUML sequence diagrams, Miro boards, IcePanel views, or simple images. The diagrams feature lets you bring these into EventCatalog as first-class, versioned resources.

### What can you do with diagrams?[​](#what-can-you-do-with-diagrams "Direct link to What can you do with diagrams?")

With diagrams in EventCatalog you can:

* **Bring any diagram type** - Mermaid, PlantUML, Miro embeds, IcePanel, Lucidchart, draw\.io, images, or any MDX content
* **Version your diagrams** - Track how your architecture visualizations evolve over time
* **Compare versions side-by-side** - See what changed between diagram versions (Scale feature)
* **Assign to any resource** - Link diagrams to domains, services, messages, or containers
* **Reuse across resources** - Reference the same diagram from multiple places in your catalog
* **Organize flexibly** - Store diagrams at the top level or nest them within domains and services
* **Ask questions with AI** - Use EventCatalog's AI assistant to ask questions about your diagrams
* **Expose to LLMs** - Diagrams are available at `.mdx` URLs (e.g., `/diagrams/my-diagram/1.0.0.mdx`) for LLM consumption

### How is this different from auto-generated diagrams?[​](#how-is-this-different-from-auto-generated-diagrams "Direct link to How is this different from auto-generated diagrams?")

| Auto-generated diagrams                   | Custom diagrams (this feature) |
| ----------------------------------------- | ------------------------------ |
| Created automatically from your resources | You create and maintain them   |
| Show relationships between catalog items  | Show anything you want         |
| Update when resources change              | Update when you version them   |
| Limited to catalog data                   | Any visual content             |

Both complement each other. Auto-generated diagrams show your system as documented in the catalog. Custom diagrams let you add context - migration plans, target architectures, sequence flows, event storming results, or embedded boards from your favorite diagramming tools.

### What do diagrams look like in EventCatalog?[​](#what-do-diagrams-look-like-in-eventcatalog "Direct link to What do diagrams look like in EventCatalog?")

Diagrams have their own dedicated pages with version switching and appear in the sidebar when assigned to resources.

![Diagram page](/assets/images/diagrams-26c11b05ecf86c175816b23a166281a9.png)

[View Demo of a Target Architecture diagram →](https://demo.eventcatalog.dev/diagrams/target-architecture/1.0.0)

### When to use custom diagrams[​](#when-to-use-custom-diagrams "Direct link to When to use custom diagrams")

Use diagrams when you want to:

* Document target architecture or migration plans
* Embed Miro boards, IcePanel views, or other collaborative diagrams
* Create sequence diagrams showing detailed message flows
* Share event storming results or architecture decision records
* Maintain historical versions of architectural diagrams
* Add visual context that can't be auto-generated from your resources

### Supported content formats[​](#supported-content-formats "Direct link to Supported content formats")

Diagrams support any content you can write in MDX:

* **Mermaid diagrams** - Flowcharts, sequence diagrams, C4 diagrams
* **PlantUML diagrams** - UML, sequence, component diagrams
* **Embedded diagrams** - Miro, IcePanel, Lucidchart, draw\.io, FigJam
* **Static images** - PNG, SVG, JPG files
* **Markdown content** - Add explanations and documentation around visuals
* **Custom components** - Use any MDX component to enhance your diagrams