# Create a diagram

Copy as Markdown[View as Markdown](/docs/development/bring-your-own-documentation/diagrams/creating-diagrams.md)

***

EventCatalog Diagrams let's you bring your own diagrams into your Catalog.

![System Architecture diagram](/assets/images/diagrams-26c11b05ecf86c175816b23a166281a9.png)

## Creating a diagram[​](#creating-a-diagram "Direct link to Creating a diagram")

### Automatic Creation[​](#automatic-creation "Direct link to Automatic Creation")

Copy this prompt and paste it into your coding agent. Your agent can help you choose where the diagram should live, create the right folder structure, and add the first version of the diagram documentation.

### Manual Creation[​](#manual-creation "Direct link to Manual Creation")

Diagrams live in a `diagrams` folder. EventCatalog discovers any `index.mdx` file inside a `diagrams` directory, regardless of where that directory lives in your catalog.

You can place diagrams:

At the root of your catalog:

* diagrams
  <!-- -->
  /
  * system-overview
    <!-- -->
    /
    * index.mdx

Inside a domain:

* domains
  <!-- -->
  /
  * E-Commerce
    <!-- -->
    /
    * diagrams
      <!-- -->
      /
      * target-architecture
        <!-- -->
        /
        * index.mdx

Inside a service:

* services
  <!-- -->
  /
  * OrderService
    <!-- -->
    /
    * diagrams
      <!-- -->
      /
      * api-flow
        <!-- -->
        /
        * index.mdx

tip

Organize diagrams close to where they're most relevant. System-wide diagrams can be placed at the root level, while resource-specific diagrams should live within that resource's folder.

## Create the diagram file[​](#create-the-diagram-file "Direct link to Create the diagram file")

Create an `index.mdx` file for the diagram.

Here is an example of a system architecture diagram:

/diagrams/system-overview/index.mdx (example)

```
---
id: system-overview
name: System Overview
version: 1.0.0
summary: High-level architecture showing all microservices and their interactions
---

## System Architecture

This diagram shows our microservices architecture:

\`\`\`mermaid
graph TB
    subgraph "Frontend"
        WebApp[Web Application]
        MobileApp[Mobile App]
    end

    subgraph "Backend Services"
        Gateway[API Gateway]
        OrderService[Order Service]
        PaymentService[Payment Service]
        InventoryService[Inventory Service]
    end

    subgraph "Data Layer"
        OrderDB[(Orders DB)]
        PaymentDB[(Payments DB)]
        Kafka[Event Stream]
    end

    WebApp --> Gateway
    MobileApp --> Gateway
    Gateway --> OrderService
    Gateway --> PaymentService
    OrderService --> Kafka
    PaymentService --> Kafka
    OrderService --> OrderDB
    PaymentService --> PaymentDB
\`\`\`

### Key Components

- **API Gateway**: Single entry point for all client requests
- **Order Service**: Handles order creation and management
- **Payment Service**: Processes payments and refunds
- **Event Stream**: Kafka for asynchronous communication
```

### Example with PlantUML[​](#example-with-plantuml "Direct link to Example with PlantUML")

/diagrams/order-flow/index.mdx (example)

```
---
id: order-flow
name: Order Processing Flow
version: 1.0.0
summary: Sequence diagram showing the complete order processing flow
---

\`\`\`plantuml
@startuml
actor Customer
participant "Order Service" as Order
participant "Payment Service" as Payment
participant "Inventory Service" as Inventory

Customer -> Order: Create Order
Order -> Inventory: Check Stock
Inventory --> Order: Stock Available
Order -> Payment: Process Payment
Payment --> Order: Payment Confirmed
Order --> Customer: Order Confirmed
@enduml
\`\`\`

## Order Processing Flow

This sequence diagram illustrates the order processing workflow:

1. Customer initiates order creation
2. Order service validates inventory availability
3. Payment is processed
4. Order confirmation is sent to customer
```

### Example with embedded diagram[​](#example-with-embedded-diagram "Direct link to Example with embedded diagram")

EventCatalog provides built-in components to embed diagrams from popular tools like Miro, IcePanel, Lucidchart, draw\.io, and FigJam. This lets you bring your existing collaborative diagrams directly into your catalog.

/diagrams/architecture-overview/index.mdx (example)

```
---
id: architecture-overview
name: Architecture Overview
version: 1.0.0
summary: Miro board showing our system architecture and design decisions
---

<Miro embedUrl="https://miro.com/app/board/..." />

## Architecture Overview

This Miro board captures our architecture decisions and system design.
Key areas covered:

- System context
- Container architecture
- Component relationships
- Technology choices
```

tip

Check out the [Diagrams documentation](/docs/components/diagram-syntax.md) to see all available diagram syntax and embed components including `<Miro>`, `<IcePanel>`, `<Lucid>`, `<DrawIO>`, and `<FigJam>`.

## Next steps[​](#next-steps "Direct link to Next steps")

Once you've created diagrams, you can:

* [Reference them from resources](/docs/development/bring-your-own-documentation/diagrams/referencing-diagrams.md) like domains, services, and messages
* [Compare diagram versions](/docs/development/bring-your-own-documentation/diagrams/comparing-diagrams.md) side-by-side