# Versioning diagrams

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

***

**Added in** `eventcatalog@3.3.0`

Diagrams in EventCatalog support versioning, allowing you to track how your architecture visualizations evolve over time. This is particularly valuable for maintaining historical accuracy and showing architectural progression.

## Why version diagrams?[​](#why-version-diagrams "Direct link to Why version diagrams?")

Versioning diagrams helps you:

* **Track architectural evolution** - Show how your system design has changed over time
* **Maintain historical accuracy** - Preserve diagrams as they existed at specific points
* **Compare versions** - See what changed between different architectural states
* **Align with resource versions** - Match diagram versions to corresponding service or domain versions
* **Document migrations** - Illustrate the journey from current state to target state

## Creating versioned diagrams[​](#creating-versioned-diagrams "Direct link to Creating versioned diagrams")

Similar to other resources in EventCatalog, diagrams use a `versioned` folder structure to maintain multiple versions.

### File structure[​](#file-structure "Direct link to File structure")

```
/diagrams/
  └── system-architecture/
      ├── index.mdx                    # Latest version (e.g., 2.0.0)
      └── versioned/
          ├── 1.0.0/
          │   └── index.mdx            # Version 1.0.0
          └── 1.5.0/
              └── index.mdx            # Version 1.5.0
```

The diagram at the root level (`/diagrams/system-architecture/index.mdx`) represents the **latest version**. Older versions are stored in the `versioned` folder, each in their own version directory.

### Example: Current state vs. target state[​](#example-current-state-vs-target-state "Direct link to Example: Current state vs. target state")

A common use case is documenting both your current architecture and your target architecture as different versions:

/diagrams/architecture/index.mdx (v2.0.0 - Target State)

```
---
id: architecture
name: System Architecture
version: 2.0.0
summary: Target microservices architecture we are migrating towards
---

## Target State (v2.0.0)

This is our target architecture - the event-driven microservices platform we are actively migrating towards.

\`\`\`mermaid
graph TB
    WebApp[Web Application]
    Gateway[API Gateway]

    subgraph "Microservices"
        OrderService[Order Service]
        PaymentService[Payment Service]
        InventoryService[Inventory Service]
    end

    Kafka[Event Stream]

    WebApp --> Gateway
    Gateway --> OrderService
    Gateway --> PaymentService
    Gateway --> InventoryService

    OrderService --> Kafka
    PaymentService --> Kafka
    InventoryService --> Kafka
\`\`\`

### Expected Outcomes

- 10x faster deployments
- 99.9% availability
- 50% cost reduction through auto-scaling
```

/diagrams/architecture/versioned/1.0.0/index.mdx (v1.0.0 - Current State)

````
---
id: architecture
name: System Architecture
version: 1.0.0
summary: Current monolithic architecture (legacy system)
---

## Current State (v1.0.0)

This represents our current monolithic architecture that we are migrating away from.

_```mermaid
graph TB
    WebApp[Web Application]
    Monolith[Monolithic Application]
    Database[(Single Database)]

    WebApp --> Monolith
    Monolith --> Database
````

### Current Limitations[​](#current-limitations "Direct link to Current Limitations")

* Single deployment unit
* Scaling challenges
* Technology constraints

````

## Version switching

When viewing a diagram that has multiple versions, EventCatalog displays a version dropdown in the header. Users can:

1. See all available versions in the dropdown
2. Switch between versions to compare changes
3. The URL updates to reflect the selected version (e.g., `/diagrams/architecture/2.0.0`)

The latest version is clearly marked in the dropdown with a "(latest)" indicator.

## Referencing specific versions

When referencing diagrams from resources, you can specify which version to link to:

```yaml title="Domain referencing specific diagram versions"
---
id: E-Commerce
name: E-Commerce Domain
version: 1.0.0
diagrams:
  # Reference the current state
  - id: architecture
    version: 1.0.0
---
````

As you update your domain to newer versions, you can update the diagram reference to match:

Updated domain referencing target architecture

```
---
id: E-Commerce
name: E-Commerce Domain
version: 2.0.0
diagrams:
  # Reference the target state
  - id: architecture
    version: 2.0.0
---
```

## Best practices[​](#best-practices "Direct link to Best practices")

### Version numbering[​](#version-numbering "Direct link to Version numbering")

Follow semantic versioning principles:

* **Major version** (2.0.0) - Significant architectural changes (e.g., monolith to microservices)
* **Minor version** (1.1.0) - New services or components added
* **Patch version** (1.0.1) - Small corrections or clarifications to the diagram

### When to create new versions[​](#when-to-create-new-versions "Direct link to When to create new versions")

Create a new diagram version when:

* The architecture fundamentally changes
* Major components are added or removed
* You want to preserve a snapshot for historical reference
* You're planning a migration and want to document both states

### Keep versions aligned[​](#keep-versions-aligned "Direct link to Keep versions aligned")

When possible, align diagram versions with the resources they document:

```
# Service at version 2.0.0
---
id: OrderService
version: 2.0.0
diagrams:
  # Reference matching diagram version
  - id: order-service-architecture
    version: 2.0.0
---
```

## Markdown export for all versions[​](#markdown-export-for-all-versions "Direct link to Markdown export for all versions")

All diagram versions support markdown export, making them accessible to LLM tools and AI assistants. Each version has its own `.mdx` endpoint:

* `/diagrams/architecture/2.0.0.mdx` - Latest version
* `/diagrams/architecture/1.0.0.mdx` - Version 1.0.0
* `/diagrams/architecture/1.5.0.mdx` - Version 1.5.0

This allows AI tools to understand the full context of your architectural evolution.