EventCatalog Documentation Creator

Generate properly formatted EventCatalog documentation files following project conventions and best practices.

Instructions

Step 1: Locate or Create the User's Catalog

Before generating any files, ask the user: "Do you already have an EventCatalog project, or would you like to create a new one?"

If they already have a catalog:

Ask: "Where is your EventCatalog project?" — It could be:
- A repo they've cloned locally (e.g., ~/projects/my-catalog/)
- A folder on their machine
- A monorepo with the catalog in a subdirectory
Verify it looks like an EventCatalog project by checking for an eventcatalog.config.js file or known directories (systems/, services/, agents/, events/, domains/, adrs/, data-products/, entities/, etc.)
Read the existing structure to understand whether they use nested (domains/services/agents/events) or flat (top-level services/, agents/, events/) organization

If they don't have a catalog yet:

Ask where they'd like to create it (default: current directory)
Run the following command to scaffold a new empty catalog:
```
npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
```
(Replace my-catalog with the user's preferred name)
This creates a ready-to-use EventCatalog project with the correct structure
All generated documentation files go inside this new catalog directory

CRITICAL: All generated files must be written to the user's catalog directory, not just displayed. Always ask where they want resources documented — never assume.

Step 2: Understand What the User Wants to Document

Ask the user what they want to document. Common scenarios:

A single service or agent and its messages
A system that groups services, containers, flows, entities, actors, and related systems
An event, command, or query
A full domain with nested services
A business flow across services and agents
A channel (Kafka topic, RabbitMQ queue, etc.)
A container (database, cache, queue)
An architecture decision record (ADR)
A data product for analytics, reporting, ML features, or operational data outputs
A domain entity or aggregate
A reusable diagram resource

Gather this information before generating:

Resource name and purpose
Version (default to 0.0.1 for new resources)
System boundary, scope (internal or external), actors, relationships, and contained resources when documenting systems
Message relationships (what it sends/receives)
Channel routing (what channels messages flow through)
Containers (what databases/caches the service reads from or writes to)
ADR links (what resources a decision applies to, and whether it supersedes/amends another ADR)
Data product lineage (inputs, outputs, contracts, freshness/SLA expectations)
Entities and relationships (identifier, properties, references, aggregate root)
Diagram notation (Mermaid, PlantUML, or other supported fenced diagram formats)
Agent model/provider and tools when documenting agents
Schema format if applicable (JSON Schema, Avro, Protobuf)

If the user points you at a codebase (not the catalog), analyze it to extract services, agents, messages, schemas, and relationships — then generate the corresponding catalog documentation.

Step 3: Check the Existing Catalog

If the catalog directory already has resources, read the existing files to understand:

Naming conventions (PascalCase IDs? kebab-case?)
Folder structure (nested under domains or flat?)
Which owners/teams are already defined
Badge styles and patterns used
Schema formats in use (JSON Schema, Avro, etc.)

Match new documentation to these existing conventions.

If the user has the EventCatalog MCP server connected:

Use getResources to see what already exists in the catalog
Use getResource to check conventions used in existing entries (naming patterns, owner formats, badge styles)
Use findResourcesByOwner to suggest consistent ownership
Use getSchemaForResource to match existing schema formats

This ensures new documentation is consistent with what's already in the catalog.

Step 4: Generate the Documentation

Generate files following the resource-specific references. Consult the appropriate reference file for the resource type:

references/services.md — Services with sends/receives, channel routing, containers
references/systems.md — Systems with scope, services, containers, flows, entities, actors, and system relationships
references/agents.md — Agents with model metadata, tools, sends/receives, containers, and flows
references/events.md — Events with schemas, payload examples, producer/consumer code
references/commands.md — Commands with REST operations and schemas
references/queries.md — Queries with REST operations and response schemas
references/domains.md — Domains with subdomains, services, and business context
references/flows.md — Business flows with steps, branching, and external systems
references/channels.md — Channels with routing, protocols, and parameters
references/containers.md — Containers (databases, caches, queues) with data classification
references/adrs.md — Architecture decision records with status, date, decision makers, appliesTo, and relationships
references/data-products.md — Data products with inputs, outputs, data contracts, lineage, and SLAs
references/entities.md — DDD/domain entities with identifiers, properties, relationships, and aggregate roots
references/diagrams.md — Reusable diagram resources (Mermaid, PlantUML, architecture diagrams)
references/ubiquitous-language.md — Ubiquitous language terms per domain (DDD glossary/dictionary)
references/teams-and-users.md — Teams and users (ownership)
references/components.md — Components (NodeGraph, Schema, Mermaid, Tabs, etc.) and resource references ([[type|Name]] wiki-style links)
references/supporting-collections.md — Changelogs, resource docs, custom docs, schemas, and Studio designs

Every resource file MUST include:

Valid YAML frontmatter between --- delimiters
id field matching existing catalog conventions
name as human-readable display name
version as semantic version string
summary as a concise 1-2 sentence description

CRITICAL: Always use index.mdx as the filename for versioned resources (systems, services, agents, events, commands, queries, domains, flows, channels, containers, ADRs, data products, entities, diagrams). Teams and users use {id}.mdx files directly. Changelogs use changelog.mdx or changelog.md. Ubiquitous language uses ubiquitous-language.mdx. Place files in the correct folder path following the nested structure pattern:

domains/{DomainName}/systems/{SystemName}/index.mdx
domains/{DomainName}/systems/{SystemName}/services/{ServiceName}/index.mdx
domains/{DomainName}/systems/{SystemName}/containers/{ContainerName}/index.mdx
domains/{DomainName}/services/{ServiceName}/events/{EventName}/index.mdx
domains/{DomainName}/agents/{AgentName}/index.mdx
domains/{DomainName}/data-products/{DataProductName}/index.mdx
domains/{DomainName}/entities/{EntityName}/index.mdx
domains/{DomainName}/diagrams/{DiagramName}/index.mdx

Or flat structure if the catalog uses that pattern:

systems/{SystemName}/index.mdx
services/{ServiceName}/index.mdx
agents/{AgentName}/index.mdx
events/{EventName}/index.mdx
adrs/{adr-id}/index.mdx
data-products/{DataProductName}/index.mdx
entities/{EntityName}/index.mdx
diagrams/{DiagramName}/index.mdx

Do not generate schemas collection entries directly. Generate or reference schema files from events, commands, or queries using schemaPath or schemas; EventCatalog creates the schemas collection from those references. Do not hand-author designs unless the user explicitly provides .ecstudio content from EventCatalog Studio.

Step 5: Validate the Output

Before presenting the files to the user, verify:

YAML frontmatter has --- delimiters on both sides
All id fields are consistent (no spaces, match folder name)
All version fields are valid semver strings (e.g., 0.0.1)
All message references in sends/receives include id and optionally version
System services, containers, flows, entities, relationships, and domain systems references include id and optionally version
System scope is either internal or external, and actor direction is either inbound or outbound
Channel routing uses to/from fields correctly in sends/receives
Schema files referenced in schemaPath actually exist or are generated
<NodeGraph /> component is included for architecture visualization
Owner IDs reference real teams/users in the catalog

Common Patterns

Documenting a Service That Processes Messages

When a user says "document my payment service that receives OrderCreated events and sends PaymentProcessed events":

Generate the service index.mdx with receives and sends arrays
If messages flow through channels, add to/from fields to the sends/receives
Generate each event index.mdx if they don't already exist in the catalog
Include <NodeGraph /> in the service body to show message flow
Generate related entities if the service owns important domain objects
Add example payload sections for each message
Place files in the correct nested folder structure

Documenting a System

When a user describes a capability, subsystem, product capability, or external system:

Decide whether the system belongs inside a domain (domains/{Domain}/systems/{System}/index.mdx) or should live at the catalog root (systems/{System}/index.mdx) because it is shared, external, or not owned by one domain
Generate the system index.mdx with scope, owners, and references to its services, containers, flows, entities, and diagrams where known
Add relationships for one-directional links to other systems, using a short label for the edge
Add actors for people, roles, or external participants, using direction: inbound when the actor interacts with the system and direction: outbound when the system reaches out to the actor
Include <ContextDiagram /> to show actors and system-to-system relationships
Include <NodeGraph /> to show the resources inside the system
Generate nested resources under the system folder when they are owned by that system, for example domains/{Domain}/systems/{System}/services/{Service}/index.mdx
If the system is nested under a domain, add it to the domain's systems frontmatter. Every system nested inside a domain MUST be referenced in that domain's index.mdx:
```
systems:
  - id: cart-system
    version: 1.0.0
  - id: promotion-system
    version: 1.0.0
```
If ADRs apply to the system boundary, persistence, integration pattern, or ownership model, link them with appliesTo: [{ type: system, id: ... }]

Documenting an Agent

When a user says "document my support agent that reads order data and uses Zendesk":

Generate the agent index.mdx with model, tools, receives/sends, readsFrom/writesTo, and flows where known
Generate or reference events/commands/queries the agent consumes or produces
Generate containers for data stores the agent reads or writes
Include <AgentTools /> when tools are documented
Include <NodeGraph /> so the agent appears in architecture visualizations
If the agent belongs to a domain, add it to the domain's agents frontmatter

Documenting a Domain

CRITICAL: A domain MUST have at least one system, service, or agent. Never create an empty domain. If the user describes a domain, ensure systems, services, or agents are identified and generated for it.

When a user wants to document a full domain:

Identify the systems, services, and agents that belong to this domain. If the user hasn't specified any, ask them: "What systems, services, or agents belong to this domain?" Do NOT create an empty domain.
Generate the domain index.mdx with the systems field listing every system, the services field listing every direct domain service, and the agents field listing every direct domain agent
Include entities, data-products, flows, and diagrams fields when those resources belong directly to the domain
Generate each system, service, and agent within the domain
Generate each message referenced by the services and agents
Generate entities, data products, diagrams, and channels if the user describes them
Use the nested folder structure: domains/{Domain}/systems/{System}/, domains/{Domain}/systems/{System}/services/{Service}/events/{Event}/, domains/{Domain}/services/{Service}/events/{Event}/, domains/{Domain}/agents/{Agent}/, domains/{Domain}/entities/{Entity}/, and domains/{Domain}/data-products/{DataProduct}/
Generate a ubiquitous-language.mdx file for the domain by extracting domain-specific terms from service names, agent names, event/command names, entities, and business processes. Place it at domains/{Domain}/ubiquitous-language.mdx. See references/ubiquitous-language.md for format and examples.
CRITICAL: After generating all files, verify the domain's frontmatter systems field lists every system, services lists every direct domain service, and agents lists every direct domain agent that belongs to it. Every system, service, or agent created directly under a domain MUST be referenced in the domain's index.mdx:
```
systems:
  - id: CheckoutSystem
services:
  - id: OrdersService
  - id: InventoryService
  - id: PaymentService
agents:
  - id: OrderSupportAgent
```
If a system, service, or agent is nested inside the domain folder but not listed in the domain's frontmatter, it will not appear as part of that domain. Always cross-check.

Documenting an ADR

When a user describes an architecture decision:

Generate adrs/{adr-id}/index.mdx
Use one of the supported statuses: proposed, accepted, rejected, deprecated, or superseded
Include a date in YYYY-MM-DD format
Add decisionMakers and owners using existing team/user IDs where known
Use appliesTo to link the decision to impacted resources (system, service, event, domain, flow, data-product, entity, etc.)
Use supersedes, supersededBy, amends, amendedBy, or related when linking ADRs together
Structure the body with Context, Decision, and Consequences

Documenting a Data Product

When a user describes analytics, reporting, BI, ML feature, or derived operational data:

Generate data-products/{DataProductName}/index.mdx or nest it under the relevant domain/subdomain
Add inputs for upstream messages, services, containers, channels, or other resources
Add outputs for produced messages, services, containers, channels, or contracts
If an output has a data contract, include contract.path, contract.name, and contract.type
Include <NodeGraph /> and any relevant <SchemaViewer /> for contract files
Document lineage, freshness, ownership, access patterns, and SLAs

Documenting an Entity

When a user describes a domain model, aggregate, data object, or business concept with properties:

Generate entities/{EntityName}/index.mdx, domains/{Domain}/entities/{EntityName}/index.mdx, or services/{Service}/entities/{EntityName}/index.mdx depending on catalog structure
Include identifier and aggregateRoot: true when applicable
Add properties with name, type, required, and description
Use references, referencesIdentifier, and relationType for relationships to other entities
Include <EntityPropertiesTable /> in the body to render the property table
Link entities from domain/service frontmatter using entities

Documenting a Diagram

When a user provides or asks for a reusable architecture, sequence, flow, or model diagram:

Generate diagrams/{DiagramName}/index.mdx or nest it under the relevant domain/subdomain
Include id, name, version, and summary
Put the diagram in the body as a fenced mermaid, plantuml, or other supported diagram block
Reference the diagram from related resources using the diagrams frontmatter field

Documenting a Business Flow

When a user describes a multi-step process:

Identify distinct steps (user actions, service calls, message exchanges, external systems)
Generate the flow index.mdx with steps array
Each step should have id, title, and appropriate type (actor, service, agent, message, externalSystem)
Connect steps with next_step or next_steps for branching

Documenting Channel Routing

When a user describes how messages flow through infrastructure:

Generate channel index.mdx files with routes for channel-to-channel routing
Update service or agent sends/receives with to/from fields pointing to channels
The full picture should show: Service or agent sends → Channel → routes to → Channel → service or agent receives

Quality Checklist

Take your time to do this thoroughly
Quality is more important than speed
Do not skip validation steps

Before delivering documentation to the user, verify every file against this checklist:

Frontmatter has valid YAML between --- delimiters
id matches the folder name
version is a valid semver string
summary is concise and meaningful (not generic)
Message relationships (sends/receives) include id
Channel routing (to/from) references valid channel IDs
Body includes <NodeGraph /> for visualization when the resource has graph relationships
Schema references point to real files
Folder structure follows catalog conventions
No duplicate resources (checked against existing catalog)
Versioned resources use index.mdx (or match the catalog's existing .md/.mdx convention); teams and users use {id}.mdx; changelogs use changelog.mdx/changelog.md
Every domain has at least one system, service, or agent — never create an empty domain
Domain systems, services, and agents frontmatter lists every direct system, service, and agent that belongs to that domain
Domain entities, data-products, flows, and diagrams frontmatter lists nested resources when present
Every domain has a ubiquitous-language.mdx file with relevant domain terms extracted from services, agents, events, commands, entities, data products, and business processes
ADRs have a valid status, date, decision makers when known, and appliesTo references for impacted resources
System scope, relationship pointers, and actor directions are valid when systems are generated
Data product contract files referenced in outputs.contract.path exist when generated

Troubleshooting

Messages Not Showing in Visualizer

If generated events/commands don't appear in the service or agent node graph:

Verify the sends/receives arrays in the service or agent frontmatter reference the exact id of the message
Ensure the message has its own index.mdx file

Schema Not Rendering

If <Schema /> or <SchemaViewer /> components show errors:

Verify schemaPath in frontmatter points to a file that exists alongside index.mdx
Check the schema file is valid JSON/Avro/Protobuf

Folder Structure Not Recognized

If resources don't appear in EventCatalog:

Verify the file is named exactly index.mdx (not INDEX.mdx or readme.md)
Verify the folder is inside a recognized collection directory (systems/, services/, agents/, events/, domains/, etc.)

System Context Diagram Not Showing Actors or Relationships

If <ContextDiagram /> does not show expected system context:

Verify the system frontmatter has relationships or actors
Verify relationships point to valid system IDs and include useful label values
Verify actor direction is inbound or outbound
If viewing a domain context diagram, verify the domain systems frontmatter references the relevant systems

Channel Routing Not Visible

If channel connections don't appear in the visualizer:

Verify the routes field in the channel frontmatter references valid channel IDs
Verify the to/from fields in service or agent sends/receives reference valid channel IDs