Introducing Entity Maps
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.
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:
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.
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!