Skip to main content

Introducing Attachments for EventCatalog

· 4 min read
David Boyne
David Boyne
Founder of EventCatalog

I'm excited to announce that EventCatalog now supports Attachments - a powerful new feature that allows you to link external resources, diagrams, and documentation directly to your domains, services, events, commands, queries, and channels.

Many teams and organizations have information scattered across different tools and platforms. This makes it difficult to find the information you need when you need it.

With Attachments, you can now link to external resources, diagrams, and documentation directly to your EventCatalog resources.

What are Attachments?​

Attachments provide a clean, organized way to reference external resources that are related to your EventCatalog resources. Whether you want to link to:

  • Architecture Decision Records (ADRs)
  • System diagrams and flowcharts
  • External documentation or wikis
  • Design documents
  • API specifications
  • Runbooks and operational guides

Attachments make it easy for your team to discover and access all the relevant information about your architecture in one place.

Why use Attachments?​

Centralized Documentation: Keep all related resources accessible from your EventCatalog, reducing context switching between different tools and platforms.

Improved Discovery: Team members can easily find relevant documentation, diagrams, and decisions related to specific services or events.

Better Context: Provide additional context and background information that helps teams understand the "why" behind your architecture decisions.

Organized Resources: Group related attachments by type (e.g., architecture-decisions, diagrams, documentation) for better organization.

Getting Started​

Adding attachments to your EventCatalog resources is straightforward. You can add them to any resource by including an attachments array in your frontmatter.

Simple URL Attachment​

events/OrderAccepted/index.mdx
---
id: OrderAccepted
name: Order Accepted
attachments:
  - https://example.com/adr/001-event-sourcing-decision
---

## Overview

This event is triggered when an order has been accepted in our system.

<Attachments />

Rich Attachments with Metadata​

For more detailed attachments, you can provide additional properties:

services/PaymentService/index.mdx
---
id: PaymentService
name: Payment Service
attachments:
  - url: https://example.com/adr/001-kafka-messaging
    title: ADR-001 - Use Kafka for asynchronous messaging
    description: Learn more about why we chose Kafka for asynchronous messaging
    type: 'architecture-decisions'
    icon: FileTextIcon
  - url: https://example.com/diagrams/payment-flow.png
    title: Payment Processing Flow
    description: Detailed flow diagram of our payment processing system
    type: 'diagrams'
    icon: FileBoxIcon
---

## Service Overview

The Payment Service handles all payment processing operations.

<Attachments />

How they look in EventCatalog​

Example output

Organizing Your Attachments​

Attachments can be grouped by type, making it easier for your team to find specific kinds of resources.

You can choose any type you want and we will group them together in the UI.

Some examples include:

  • architecture-decisions: ADRs, technical decisions, design rationale
  • diagrams: System diagrams, flowcharts, architecture visualizations
  • documentation: User guides, API docs, operational runbooks
  • external-tools: Links to monitoring dashboards, admin panels, etc.

You can choose from any icon in the Lucide Icons library to represent your attachments.

Supported Resources​

The Attachments feature works across all EventCatalog resource types:

  • Domains
  • Services
  • Events
  • Commands
  • Queries
  • Channels
  • Custom documentation pages

Get Started Today​

If you already have an EventCatalog, simply upgrade to the latest version to start using Attachments.

Don't have a catalog yet?

Create a new EventCatalog to try out Attachments:

npx @eventcatalog/create-eventcatalog@latest my-catalog

SDK​

If you are using the EventCatalog SDK, you can update the latest version to get the Attachments feature.

Summary​

Attachments provide a simple yet powerful way to connect all your relevant documentation, diagrams, and external resources directly to your EventCatalog resources.

This feature can help you and your team maintain better context, improves documentation discovery, and creates a more comprehensive view of your architecture.

If you have any questions, feature ideas, or would like to discuss EventCatalog features with your team, join our Discord community.

Using EventCatalog?​

Want to learn more about EventCatalog and how it can help you? Reach out to me on socials or Discord, and I would be happy to join a call with you and your team.