Skip to main content

Introducing Entity Maps

· 4 min read
David Boyne
David Boyne
Founder of EventCatalog

Understanding the relationships between entities in your domain model is crucial for building robust event-driven architectures. That's why we're excited to introduce Entity Maps — a powerful new visualization feature that helps you explore and understand entity relationships within your EventCatalog domains.

What are Entity Maps?​

Entity Maps provide a visual representation of how entities connect within your domains. In Domain-Driven Design, entities are the core building blocks that represent key concepts like Order, Customer, or Invoice. Entity Maps help you visualize these relationships at a glance, making it easier to understand your domain architecture and identify potential improvements.

EventCatalog Entity MapView the demo

Why Entity Maps are useful​

Entity Maps solve several common challenges teams face when working with complex domain models:

Visual Domain Understanding​

Instead of piecing together entity relationships from scattered documentation, Entity Maps provide a comprehensive visual overview of your domain model. You can instantly see how entities connect and understand the flow of data through your system.

Architectural Insights​

By visualizing entity relationships, you can identify potential architectural improvements, spot missing connections, or discover opportunities to simplify your domain model. Entities that are referenced across domains are highlighted in yellow, making cross-domain dependencies immediately visible.

Team Collaboration​

Entity Maps serve as a common language for discussing domain models with both technical and non-technical stakeholders. They make it easier to communicate complex relationships and ensure everyone shares the same understanding of the domain.

Design Validation​

When designing new features or refactoring existing ones, Entity Maps help you validate that your entity relationships align with your business requirements and domain boundaries.

How to get started​

Getting started with Entity Maps is straightforward if you already have entities documented in EventCatalog:

Don't have entities yet?

You can read the Entity API documentation to learn how to create entities.

1. Define Entity Relationships​

To create meaningful Entity Maps, you'll need to define relationships between your entities using reference fields:

---
id: OrderItem
name: OrderItem
version: 1.0.0
properties:
  - name: orderId
    type: UUID
    required: true
    description: Identifier for the parent Order
    references: Order
    relationType: hasOne
    referencesIdentifier: orderId
---

2. View Your Entity Map​

Once you've defined entity relationships, you can view your Entity Map in two ways:

Full-screen Visualizer: Navigate to /visualiser/domains/{domain-name}/{version}/entity-map for a comprehensive view with interactive controls, zoom capabilities, and filtering options.

Embedded Component: Use the <EntityMap id="domain-name" /> component to embed entity maps directly in your documentation pages.

3. Explore and Interact​

Entity Maps are fully interactive — click and drag to explore relationships, zoom in for detailed views, and hover over entities to see their properties and descriptions.

To get started and learn more you can read the Entity Maps documentation.

Embed Entity Maps in Backstage​

If you're using Backstage, you can embed Entity Maps directly in your entity pages using the <EventCatalogEntityEntityMapCard /> component from our Backstage plugin. This brings your domain visualizations right into your developer portal.

EventCatalog Entity Map in BackstageLearn more about the Backstage integration

Start visualizing your domain today​

Entity Maps are available now in EventCatalog. If you're already documenting entities, you can start creating entity maps immediately by defining relationships between your entities.

To learn more about Entity Maps and how to use them effectively, check out our comprehensive documentation or explore the interactive demo.

Whether you're working with Domain-Driven Design principles or simply want to better understand your system's data model, Entity Maps provide the visual clarity you need to build better event-driven architectures.

If you have any questions or want to join our community of over 1,200 people exploring EventCatalog and event-driven architecture, feel free to join us on Discord!