Changelog

Highlights

EventCatalog v4 is shaped around a bigger vision: EventCatalog as the graph of your software architecture, not just your events. This release introduces systems — a new resource type for documenting software capabilities and external systems — along with system context maps, a simplified Discover experience, and a more generous Community Edition. Read the full story in Introducing EventCatalog v4.

New Features

• Systems — A new versioned resource type that sits between domains and implementation detail. Systems group the services, flows, entities, data stores, and diagrams that work together to deliver a capability (e.g. checkout, payment processing, or a third-party provider like Stripe). Systems can be defined at the top level or nested inside a domain, get their own architecture overview page and icon/color in the sidebar, can be owned by teams and users, and can be targeted by ADRs via appliesTo: [{ type: 'system' }].
• System Context Maps — Systems can declare relationships to other systems and actors (people or roles that interact with them). EventCatalog renders these as a new Context Diagram, viewable globally at /visualiser/system-context-map or per-system at /visualiser/systems/{id}/{version}/context. External systems (e.g. SaaS providers) are visually badged as "External System".
• System resource diagrams — Add <NodeGraph /> to a system page to render the services, flows, entities, and data stores that make up that system, complementing the higher-level Context Diagram.
• Simplified Discover experience — Resource-specific Browse sidebar links have been replaced with a single Discover page and a Kind filter, so users can browse domains, systems, services, messages, flows, entities, data stores, ADRs, and teams from one place without needing to know which resource type they're looking for.
• Systems in the SDK and AI tools — The SDK now supports reading and writing systems, adding resources to systems, and attaching systems to domains. EventCatalog Assistant, the MCP server, and catalog tools also understand systems, enabling questions like "What services make up the Payment Processing System?".
• Custom homepages now in Community Edition — Build a custom pages/homepage.astro without needing a paid plan, and embed the new SystemContextMap component directly on it.

Improvements

• Configurable Application sidebar via navigation.groups — Define custom navigation groups for the vertical sidebar, including labels, Lucide icons, custom links, ordering, active-route matching, and bottom-positioned groups. See the application sidebar guide.
• Top level diagrams navigation group — A new sidebar group surfaces the System Context Map below top-level domains whenever systems exist in your catalog.
• Diagram version comparison available to everyone — No longer gated behind the Scale plan.
• Astro 7 upgrade — EventCatalog now runs on Astro 7 internally, with markdown/MDX processing migrated to the new unified processor API.
• New default template — create-eventcatalog now scaffolds a fuller e-commerce example catalog with domains, systems, services, and messages.

Breaking Changes

• Export to PDF removed — The Export to PDF / print feature has been removed. Update any internal guidance that references exporting pages to PDF.
• /visualiser/context-map removed — Replaced by the new system context map routes (/visualiser/system-context-map, /visualiser/systems/{id}/{version}/context, /visualiser/domains/{id}/{version}/systems-context). Update any custom links or bookmarks.
• Top-level sidebar config removed — The old sidebar visibility config in eventcatalog.config.js has been replaced by navigation.groups. If you don't customize the sidebar, no action is needed. The SideBarConfig type export has also been removed.

See the v4 upgrade guide for full migration steps.

Bug Fixes

• Fixed the dev watcher incorrectly matching generated files when IGNORE_BUILD_ARTIFACTS is set, which could cause unrelated generated files to be picked up during local development.
• Restricted the EntityMap MDX component's collection prop to domains or services only.

Business Model Changes

• EventCatalog trials now last 30 days.
• The Starter plan has been removed; paid self-hosted features and EventCatalog Cloud are now organized around the Scale plan, and integrations are now available on Scale. Existing customers are grandfathered on their current plans.

New Features

• Schema Fields Explorer — A brand-new page that lets you explore every field across all your schemas. Trace which messages share the same fields and detect naming conflicts across your architecture. Includes a modern redesigned layout with dark mode support. Learn more.
• Export to PDF — Message pages can now be exported as PDFs, making it easy to share schema documentation with stakeholders outside your catalog.
• Usage Examples for Messages — Messages now support usage examples directly in the schema explorer. Default templates include examples out of the box to help new users get started faster.
• Analytics Integrations — Built-in support for Google Analytics 4, Google Tag Manager, and PostHog so you can track how your team uses the catalog.
• Flows in Nested Directories — Flows can now live inside domain and service directories, making it easier to co-locate flow documentation with the services they describe.

Improvements

• Astro 6, Vite 7, and Zod 4 — Upgraded the entire core framework stack. Faster builds, improved SSR stability, and access to the latest Astro features.
• Governance: Schema Change Detection — A new schema_changed trigger lets you define governance rules that fire when message schemas are modified. Pair with the new fail action type for CI/CD gating that blocks merges when schema contracts are broken. Learn more.
• Governance: Message Deprecation Trigger — Get notified via console or webhooks when a message is deprecated, so downstream teams can plan their migration.
• Generator Resilience — Generators that fail no longer stop the entire build. Other generators continue running so you still get a partial catalog even when one source has issues.

Generator Updates

• AsyncAPI 3.1.0 Support — The AsyncAPI generator now supports the latest 3.1.0 specification.
• Parse Examples (AsyncAPI & OpenAPI) — Both generators can now parse examples from your specs and include them in the generated catalog with the new parseExamples option.
• Subdomain Service Paths — Generators can now place services into subdomain directory paths, matching how teams organize services under business domains.
• Attach Headers to Schema (AsyncAPI) — A new attachHeadersToSchema option combines message headers with payload into a single unified schema view.
• Channel Server Protocols (AsyncAPI) — Channel protocol detection now reads server protocol information, giving you accurate protocol labels on channels.
• Circular Reference Handling (AsyncAPI) — The generator now gracefully handles circular references in oneOf/allOf schemas instead of crashing.
• Confluent Schema Registry Auth Fix — Fixed authentication issues with the Confluent Schema Registry generator for users with custom auth setups.

New Features

• Tailwind CSS v4 — Migrated from Tailwind CSS v3 to v4 with the native Vite plugin. Dev server startup dropped from ~6.7s to ~1.1s and first page time-to-first-byte went from ~6.7s to ~1.7s.
• Channels in Service Sidebar — Services now display their associated channels in the sidebar, making it easier to see which channels a service publishes to or subscribes from.
• Changelog Quick Reference — A changelog link is now available in the left sidebar Quick Reference section for all resource types.

Improvements

• Architecture Change Detection (CLI) — A new governance check command in the EventCatalog CLI detects when services start or stop producing or consuming messages. Define rules in a governance.yaml file and get notified via console or webhooks. Works in CI/CD pipelines to catch architecture changes before they merge. Learn more.
• SDK now includes changelog helper methods for programmatic access to resource changelogs.

Improvements

• Refined UI Theme — Improved sidebar active states with accent colors, brighter dark mode text, subtle gradients on the homepage, and dark mode icon invert support for a more polished look.
• Visualiser Base Path Support — The visualiser now supports configurable base paths, so it works correctly when EventCatalog is deployed under a subpath.

Bug Fixes

• Fixed dark mode styling for embedded Flow borders and footer text.
• Fixed service sidebar entities rendering as unresolved pointers instead of navigable links.
• Fixed first-run Vite dep-scan errors by improving file watcher configuration.

New Features

• DSL Message Hydration — Messages are now hydrated in DSL exports with shared managed keys across all message types, making DSL round-trips more reliable.
• EventCatalog Compass — The DSL playground has been rebranded to EventCatalog Compass, a browser-based tool for authoring and visualising your architecture using the EventCatalog DSL.

Bug Fixes

• Fixed query edge labels in the visualiser.
• Fixed resource docs not appearing when folder name differs from frontmatter id.
• Fixed resource docs glob patterns to support nested directory structures.
• Fixed MCP server to create fresh transport per request, resolving stateless transport reuse errors.

New Features

• Semver Version Matching in Visualiser — Services can now use semver range patterns (^1.0.0, ~1.2.0) and x-patterns (1.x, 1.2.x) in their sends and receives configurations, and these will correctly resolve in the visualiser.

Bug Fixes

• Fixed visualiser incorrectly routing all event versions to the same channel. When a service sends multiple versions of the same event to different channels, each version now routes to its correct channel.

New Features

• Resource Docs — Attach additional documentation pages to any catalog resource (services, events, domains, etc.). Organize supplementary docs alongside your resources for richer documentation. Learn more.
• Doc Resource References — Use [[doc|PageName]] syntax to create inline references to custom documentation pages with hover tooltips.

Improvements

• Replaced concurrently with native process management for cleaner dev server output, now showing EventCatalog version instead of Astro version.
• Upgraded AsyncAPI React component to v3.
• Fixed dark theme support on custom documentation pages.

New Features

• Lazy-Loaded Search — Search index now loads on intent rather than at startup, significantly reducing initial page load time.
• Deferred Hydration — Search and sidebar components now hydrate on interaction instead of on page load, reducing JavaScript execution on first render.

Improvements

• Faster Dev Server — First request after startup is now prewarmed automatically, cutting perceived latency.
• Lazy-Loaded Viewers — Heavy graph and OpenAPI viewers are now loaded on demand rather than bundled upfront.
• Compact Search API — Search index payload has been compacted to reduce network transfer size.
• Gated Visualiser Routes — Static route generation for the visualiser is now skipped when disabled, speeding up builds.
• Fixed AsyncAPI remote schema resolution to properly pass auth headers.
• Fixed RemoteSchema environment variable placeholders in SSR mode.
• Fixed content collection glob patterns to exclude dist directories.
• Fixed theme toggle hydration mismatch in dark mode.

Improvements

• Monorepo Restructure — EventCatalog is now organized as a monorepo with Turborepo and pnpm workspaces. This improves build times, makes contributing easier, and enables independent versioning of packages like the visualiser, SDK, and CLI.
• Fixed visualiser header visibility conflicts with Tailwind utilities.

New Features

• Visualizer Focus Mode — Click any node in the visualizer to open a focus mode panel. See the selected node in the center with incoming connections on the left and outgoing on the right. Click connected nodes to switch focus with smooth slide animations. Includes documentation links and zoom controls.
• Clickable Folder Navigation — Custom documentation pages now support clickable folder navigation when index files exist, making it easier to browse nested documentation.

Improvements

• Migrated the visualiser into a standalone package, enabling reuse outside of EventCatalog core.
• Refactored collection getters with a reverse index for faster producer/consumer resolution.
• Fixed PlantUML rendering race condition that could cause diagrams to fail on first load.
• Fixed MCP server compatibility with Vercel AI SDK tool() helper.
• Security fix: patched prismjs CVE-2024-53382.

New Features

• Visualizer Layout Persistence — Save and restore custom node positions in the visualizer during development. Drag nodes to arrange your visualization, then save layouts to _data/visualizer-layouts/ for sharing with your team. Layouts work across all visualizers including services, events, flows, domains, entity maps, and designs. Available in dev mode only.

New Features

• Build Telemetry — Added resource counting to build telemetry, tracking the number of events, services, domains, and other resources in your catalog. This helps teams monitor catalog growth and understand the scale of their architecture documentation.

Improvements

• Configurable Mermaid Diagram Size — Added configurable maxTextSize parameter for Mermaid diagrams, allowing you to render larger and more complex diagrams without rendering issues.

New Features

• Mermaid Export for NodeGraph — Export NodeGraph visualizations as Mermaid diagrams with view mode switching and shareable URLs. This makes it easier to share and embed your architecture visualizations in documentation or presentations.

Bug Fixes

• Fixed containers collection glob pattern to properly support nested directories, improving organization flexibility for container resources.

Bug Fixes

• Fixed issue with custom documentation pages not rendering correctly on Windows systems, improving cross-platform compatibility.

Bug Fixes

• Fixed TypeScript type errors in data product builder test file by adding proper type casting and missing required fields, improving type safety and developer experience.

New Features

• Data Products Collection — Added support for documenting Data Products as a new collection type in EventCatalog. Teams can now catalog and track data products alongside events, services, and domains, providing a complete view of their data architecture.

Improvements

• Extracted shared specification processing utilities to reduce code duplication and improve maintainability across the codebase.

Improvements

• Enhanced Schema Viewer — Added comprehensive support for oneOf and anyOf JSON Schema keywords, including:

  • Complete handling for anyOf in schema processing
  • Fixed oneOf rendering to show selected variant's properties
  • Added variant selector UI for nested oneOf/anyOf within properties
  • Support for oneOf/anyOf in array items
  • Variant type indicators in property type display

• Updated Astro dependencies to latest versions for improved performance and security.

New Features

• Direct Domain Event Flows — Added sends and receives properties to domains, allowing domains to directly document event flows without requiring services as intermediaries. This simplifies modeling domain-to-domain communication patterns and provides a clearer view of event-driven architecture at the domain level.

Improvements

• Added type check script and fixed type errors in ResourceRef and SearchModal components for improved type safety.
• Directory navigation now defaults to the teams page when no users are defined, providing a better user experience.

New Features

• Inline Resource References — Added wiki-style syntax for creating interactive resource links. Use [[type|ResourceName]] syntax to create links that display resource details on hover, making it easier to reference and explore related resources directly within your documentation.

Improvements

• Updated Hono version for improved performance and security.
• Fixed sidebar favorites removal for deleted nodes and added theme support to plans and custom documentation pages.

New Features

• Discover Page — Added a new Discover page with enhanced table filtering and tabbed navigation for browsing catalog resources. This makes it easier to explore and find services, events, domains, and other resources across your entire catalog.

Improvements

• Reduced build size through optimized sidebar implementation using node references and static JSON API.

Bug Fixes

• Fixed visualizer showing incorrect "subscribed by" edge when a producer references a non-existent channel version, improving accuracy of relationship visualization.

Bug Fixes

• Fixed Avro schema file downloads in context menu by using the actual schema filename from schemaPath instead of a hardcoded 'schema.json' value, ensuring downloaded files have the correct name.

Improvements

• Enhanced Sidebar Search — Improved sidebar search with several enhancements:
  • Fixed duplicate search results by filtering out unversioned node keys
  • Added grouping of search results by type with alphabetical sorting
  • Added missing Channel type to filter mapping
  • Extracted shared badge styling utilities using CSS variables for consistent theming

Bug Fixes

• Fixed search results not respecting base path and trailing slash configuration, ensuring search URLs correctly include configured base path and trailing slash settings.

Bug Fixes

• Fixed React Rules of Hooks violation in NestedSideBar component by moving isFavorited hook before early returns, ensuring proper hook execution order.

New Features

• Interactive Diagram Controls — Added interactive controls to Mermaid and PlantUML diagrams, enabling pan, zoom, and other interactions for better diagram exploration and readability.

New Features

• MCP Server Support — Added Model Context Protocol (MCP) server and shared catalog tools, enabling better integration with AI tools and external systems for querying and interacting with your catalog data.

Bug Fixes

• Fixed schema explorer rendering issue in server-side rendering (SSR) mode on application start, ensuring schemas display correctly on initial page load.

New Features

• Diagrams as Resources — Added support for diagrams as a new resource type, allowing you to document and organize architectural diagrams alongside your other catalog resources for a more complete documentation experience.

Bug Fixes

• Fixed changelog theme styles to ensure proper styling across light and dark themes.

New Features

• IcePanel Diagrams — Added support for embedding IcePanel diagrams in your catalog, enabling teams using IcePanel for C4 model diagrams to integrate them directly into their EventCatalog documentation.

New Features

• Custom AI Assistant Tools — Added the ability to add custom tools to the AI Assistant, enabling teams to extend the assistant's capabilities with domain-specific functionality tailored to their catalog and workflows. Learn more in the EventCatalog Assistant documentation.

New Features

• Dark Mode and Custom Themes — Added full support for dark mode and custom themes, allowing teams to customize the appearance of their catalog to match their brand or preferences. Users can toggle between light and dark modes, and administrators can configure custom color schemes.

Highlights

EventCatalog v3 is a ground-up rebuild, delivering a faster, more intuitive experience for documenting and exploring your event-driven architecture. Whether you're onboarding new engineers or investigating production issues, v3 helps you find what you need, when you need it.

New Features

• EventCatalog Assistant — Bring any AI model to your catalog. Ask questions about your architecture in natural language and get instant answers. Works with OpenAI, Anthropic, or any compatible model.

• Redesigned Homepage — A new landing experience that gives teams an instant overview of their architecture, with quick access to services, events, and domains.

• Customizable Documentation Sidebar — Full control over how your documentation is organized. Create custom sections, reorder content, and build the navigation that works for your team.

• New Search Experience — Faster, smarter search with improved relevance and filtering. Find services, events, and documentation across your entire catalog instantly.

• Channel Support — Added channel support in navigation and search for better organization of messaging channels.

• Visualizer Presentation Mode — Visualizations now include a presentation mode for sharing architecture diagrams in meetings and presentations.

• Admonition Titles — Added support for custom titles on admonition blocks for better documentation clarity.

Performance

• New Caching System — Dramatically faster build times and page loads through intelligent caching of catalog data and visualizations.

• Simplified Sidebars — Streamlined navigation reduces cognitive load and makes exploring your architecture more intuitive.

Architecture Changes

• Updated Domain Hierarchy — Improved structure for organizing domains and subdomains, better reflecting how teams think about bounded contexts.

• Improved Overview Pages — Architecture overview pages now provide richer context with better visualizations and relationship mapping.

Improvements

• Updated architecture overview page designs for better clarity and usability
• Added icons to specification files in the sidebar for easier identification
• Improved Ubiquitous Language styling throughout the catalog
• Enhanced table styles for better readability
• Refactored features into Astro custom integrations for better modularity
• Updated logger for improved debugging and development experience
• Explicit opt-in for authentication features
• llms.txt now enabled by default for better AI integration
• Removed redundant code and files for cleaner codebase

Bug Fixes

• Fixed embedding pages on build to ensure proper page generation
• Fixed issue with nested sidebar state management
• Resolved deployment issues for example catalogs on releases
• Fixed search functionality throughout the application
• Corrected duplicate edge labels in visualizations
• Fixed accessibility issues across the catalog
• Resolved AsyncAPI loading issues in the DOM
• Fixed MDX pages not being added to teams and users sections
• Corrected circular dependency issues in JavaScript

Migration Notes

The following features have been deprecated or replaced:

• EventCatalog Chat → replaced with EventCatalog Assistant
• Chat prompts → removed (use Assistant instead)
• .md files → use .mdx files for all content
• LIST_VIEW and SIDE_VIEW → replaced with new navigation system
• Governance reports → deprecated

See the v3 upgrade guide for complete migration instructions.