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:
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
1---
2name: catalog-documentation-creator
3description: Generates EventCatalog documentation files (systems, services, agents, events, commands, queries, domains, flows, channels, containers, ADRs, data products, entities, diagrams) with correct frontmatter, folder structure, and best practices. Use when user asks to "document a system", "document a service", "document an agent", "document an AI agent", "create EventCatalog files", "add an event to the catalog", "document my architecture", "generate catalog documentation", "create documentation for my microservice", "document a database", "create an ADR", "document a data product", or "document an entity".
4license: MIT
5metadata:
6 source: https://skillmd.com/skills/event-catalog/catalog-documentation-creator
7 author: eventcatalog
8 version: "1.0.0"
9---
10
11# EventCatalog Documentation Creator
12
13Generate properly formatted EventCatalog documentation files following project conventions and best practices.
14
15## Instructions
16
17### Step 1: Locate or Create the User's Catalog
18
19Before generating any files, ask the user: **"Do you already have an EventCatalog project, or would you like to create a new one?"**
20
21**If they already have a catalog:**
22- Ask: **"Where is your EventCatalog project?"** — It could be:
23 - A repo they've cloned locally (e.g., `~/projects/my-catalog/`)
24 - A folder on their machine
25 - A monorepo with the catalog in a subdirectory
26- 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.)
27- Read the existing structure to understand whether they use **nested** (domains/services/agents/events) or **flat** (top-level services/, agents/, events/) organization
28
29**If they don't have a catalog yet:**
30- Ask where they'd like to create it (default: current directory)
31- Run the following command to scaffold a new empty catalog:
32 ```bash
33 npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
34 ```
35 (Replace `my-catalog` with the user's preferred name)
36- This creates a ready-to-use EventCatalog project with the correct structure
37- All generated documentation files go inside this new catalog directory
38
39CRITICAL: All generated files must be written to the user's catalog directory, not just displayed. Always ask where they want resources documented — never assume.
40
41### Step 2: Understand What the User Wants to Document
42
43Ask the user what they want to document. Common scenarios:
44
45- A single service or agent and its messages
46- A system that groups services, containers, flows, entities, actors, and related systems
47- An event, command, or query
48- A full domain with nested services
49- A business flow across services and agents
50- A channel (Kafka topic, RabbitMQ queue, etc.)
51- A container (database, cache, queue)
52- An architecture decision record (ADR)
53- A data product for analytics, reporting, ML features, or operational data outputs
54- A domain entity or aggregate
55- A reusable diagram resource
56
57Gather this information before generating:
58- Resource name and purpose
59- Version (default to `0.0.1` for new resources)
60- System boundary, scope (`internal` or `external`), actors, relationships, and contained resources when documenting systems
61- Message relationships (what it sends/receives)
62- Channel routing (what channels messages flow through)
63- Containers (what databases/caches the service reads from or writes to)
64- ADR links (what resources a decision applies to, and whether it supersedes/amends another ADR)
65- Data product lineage (inputs, outputs, contracts, freshness/SLA expectations)
66- Entities and relationships (identifier, properties, references, aggregate root)
67- Diagram notation (Mermaid, PlantUML, or other supported fenced diagram formats)
68- Agent model/provider and tools when documenting agents
69- Schema format if applicable (JSON Schema, Avro, Protobuf)
70
71If 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.
72
73### Step 3: Check the Existing Catalog
74
75If the catalog directory already has resources, read the existing files to understand:
76- Naming conventions (PascalCase IDs? kebab-case?)
77- Folder structure (nested under domains or flat?)
78- Which owners/teams are already defined
79- Badge styles and patterns used
80- Schema formats in use (JSON Schema, Avro, etc.)
81
82Match new documentation to these existing conventions.
83
84If the user has the EventCatalog MCP server connected:
85
861. Use `getResources` to see what already exists in the catalog
872. Use `getResource` to check conventions used in existing entries (naming patterns, owner formats, badge styles)
883. Use `findResourcesByOwner` to suggest consistent ownership
894. Use `getSchemaForResource` to match existing schema formats
90
91This ensures new documentation is consistent with what's already in the catalog.
92
93### Step 4: Generate the Documentation
94
95Generate files following the resource-specific references. Consult the appropriate reference file for the resource type:
96
97- `references/services.md` — Services with sends/receives, channel routing, containers
98- `references/systems.md` — Systems with scope, services, containers, flows, entities, actors, and system relationships
99- `references/agents.md` — Agents with model metadata, tools, sends/receives, containers, and flows
100- `references/events.md` — Events with schemas, payload examples, producer/consumer code
101- `references/commands.md` — Commands with REST operations and schemas
102- `references/queries.md` — Queries with REST operations and response schemas
103- `references/domains.md` — Domains with subdomains, services, and business context
104- `references/flows.md` — Business flows with steps, branching, and external systems
105- `references/channels.md` — Channels with routing, protocols, and parameters
106- `references/containers.md` — Containers (databases, caches, queues) with data classification
107- `references/adrs.md` — Architecture decision records with status, date, decision makers, appliesTo, and relationships
108- `references/data-products.md` — Data products with inputs, outputs, data contracts, lineage, and SLAs
109- `references/entities.md` — DDD/domain entities with identifiers, properties, relationships, and aggregate roots
110- `references/diagrams.md` — Reusable diagram resources (Mermaid, PlantUML, architecture diagrams)
111- `references/ubiquitous-language.md` — Ubiquitous language terms per domain (DDD glossary/dictionary)
112- `references/teams-and-users.md` — Teams and users (ownership)
113- `references/components.md` — Components (NodeGraph, Schema, Mermaid, Tabs, etc.) and resource references (`[[type|Name]]` wiki-style links)
114- `references/supporting-collections.md` — Changelogs, resource docs, custom docs, schemas, and Studio designs
115
116Every resource file MUST include:
117
118- Valid YAML frontmatter between `---` delimiters
119- `id` field matching existing catalog conventions
120- `name` as human-readable display name
121- `version` as semantic version string
122- `summary` as a concise 1-2 sentence description
123
124CRITICAL: 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:
125
126```
127domains/{DomainName}/systems/{SystemName}/index.mdx
128domains/{DomainName}/systems/{SystemName}/services/{ServiceName}/index.mdx
129domains/{DomainName}/systems/{SystemName}/containers/{ContainerName}/index.mdx
130domains/{DomainName}/services/{ServiceName}/events/{EventName}/index.mdx
131domains/{DomainName}/agents/{AgentName}/index.mdx
132domains/{DomainName}/data-products/{DataProductName}/index.mdx
133domains/{DomainName}/entities/{EntityName}/index.mdx
134domains/{DomainName}/diagrams/{DiagramName}/index.mdx
135```
136
137Or flat structure if the catalog uses that pattern:
138
139```
140systems/{SystemName}/index.mdx
141services/{ServiceName}/index.mdx
142agents/{AgentName}/index.mdx
143events/{EventName}/index.mdx
144adrs/{adr-id}/index.mdx
145data-products/{DataProductName}/index.mdx
146entities/{EntityName}/index.mdx
147diagrams/{DiagramName}/index.mdx
148```
149
150Do 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.
151
152### Step 5: Validate the Output
153
154Before presenting the files to the user, verify:
155
156- YAML frontmatter has `---` delimiters on both sides
157- All `id` fields are consistent (no spaces, match folder name)
158- All `version` fields are valid semver strings (e.g., `0.0.1`)
159- All message references in `sends`/`receives` include `id` and optionally `version`
160- System `services`, `containers`, `flows`, `entities`, `relationships`, and domain `systems` references include `id` and optionally `version`
161- System `scope` is either `internal` or `external`, and actor `direction` is either `inbound` or `outbound`
162- Channel routing uses `to`/`from` fields correctly in sends/receives
163- Schema files referenced in `schemaPath` actually exist or are generated
164- `<NodeGraph />` component is included for architecture visualization
165- Owner IDs reference real teams/users in the catalog
166
167## Common Patterns
168
169### Documenting a Service That Processes Messages
170
171When a user says "document my payment service that receives OrderCreated events and sends PaymentProcessed events":
172
1731. Generate the service `index.mdx` with `receives` and `sends` arrays
1742. If messages flow through channels, add `to`/`from` fields to the sends/receives
1753. Generate each event `index.mdx` if they don't already exist in the catalog
1764. Include `<NodeGraph />` in the service body to show message flow
1775. Generate related entities if the service owns important domain objects
1786. Add example payload sections for each message
1797. Place files in the correct nested folder structure
180
181### Documenting a System
182
183When a user describes a capability, subsystem, product capability, or external system:
184
1851. 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
1862. Generate the system `index.mdx` with `scope`, `owners`, and references to its `services`, `containers`, `flows`, `entities`, and `diagrams` where known
1873. Add `relationships` for one-directional links to other systems, using a short `label` for the edge
1884. 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
1895. Include `<ContextDiagram />` to show actors and system-to-system relationships
1906. Include `<NodeGraph />` to show the resources inside the system
1917. Generate nested resources under the system folder when they are owned by that system, for example `domains/{Domain}/systems/{System}/services/{Service}/index.mdx`
1928. 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`:
193 ```yaml
194 systems:
195 - id: cart-system
196 version: 1.0.0
197 - id: promotion-system
198 version: 1.0.0
199 ```
2009. If ADRs apply to the system boundary, persistence, integration pattern, or ownership model, link them with `appliesTo: [{ type: system, id: ... }]`
201
202### Documenting an Agent
203
204When a user says "document my support agent that reads order data and uses Zendesk":
205
2061. Generate the agent `index.mdx` with `model`, `tools`, `receives`/`sends`, `readsFrom`/`writesTo`, and `flows` where known
2072. Generate or reference events/commands/queries the agent consumes or produces
2083. Generate containers for data stores the agent reads or writes
2094. Include `<AgentTools />` when tools are documented
2105. Include `<NodeGraph />` so the agent appears in architecture visualizations
2116. If the agent belongs to a domain, add it to the domain's `agents` frontmatter
212
213### Documenting a Domain
214
215CRITICAL: 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.
216
217When a user wants to document a full domain:
218
2191. 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.
2202. 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
2213. Include `entities`, `data-products`, `flows`, and `diagrams` fields when those resources belong directly to the domain
2224. Generate each system, service, and agent within the domain
2235. Generate each message referenced by the services and agents
2246. Generate entities, data products, diagrams, and channels if the user describes them
2257. 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}/`
2268. 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.
2279. 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`:
228 ```yaml
229 systems:
230 - id: CheckoutSystem
231 services:
232 - id: OrdersService
233 - id: InventoryService
234 - id: PaymentService
235 agents:
236 - id: OrderSupportAgent
237 ```
238 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.
239
240### Documenting an ADR
241
242When a user describes an architecture decision:
243
2441. Generate `adrs/{adr-id}/index.mdx`
2452. Use one of the supported statuses: `proposed`, `accepted`, `rejected`, `deprecated`, or `superseded`
2463. Include a `date` in `YYYY-MM-DD` format
2474. Add `decisionMakers` and `owners` using existing team/user IDs where known
2485. Use `appliesTo` to link the decision to impacted resources (`system`, `service`, `event`, `domain`, `flow`, `data-product`, `entity`, etc.)
2496. Use `supersedes`, `supersededBy`, `amends`, `amendedBy`, or `related` when linking ADRs together
2507. Structure the body with `Context`, `Decision`, and `Consequences`
251
252### Documenting a Data Product
253
254When a user describes analytics, reporting, BI, ML feature, or derived operational data:
255
2561. Generate `data-products/{DataProductName}/index.mdx` or nest it under the relevant domain/subdomain
2572. Add `inputs` for upstream messages, services, containers, channels, or other resources
2583. Add `outputs` for produced messages, services, containers, channels, or contracts
2594. If an output has a data contract, include `contract.path`, `contract.name`, and `contract.type`
2605. Include `<NodeGraph />` and any relevant `<SchemaViewer />` for contract files
2616. Document lineage, freshness, ownership, access patterns, and SLAs
262
263### Documenting an Entity
264
265When a user describes a domain model, aggregate, data object, or business concept with properties:
266
2671. Generate `entities/{EntityName}/index.mdx`, `domains/{Domain}/entities/{EntityName}/index.mdx`, or `services/{Service}/entities/{EntityName}/index.mdx` depending on catalog structure
2682. Include `identifier` and `aggregateRoot: true` when applicable
2693. Add `properties` with `name`, `type`, `required`, and `description`
2704. Use `references`, `referencesIdentifier`, and `relationType` for relationships to other entities
2715. Include `<EntityPropertiesTable />` in the body to render the property table
2726. Link entities from domain/service frontmatter using `entities`
273
274### Documenting a Diagram
275
276When a user provides or asks for a reusable architecture, sequence, flow, or model diagram:
277
2781. Generate `diagrams/{DiagramName}/index.mdx` or nest it under the relevant domain/subdomain
2792. Include `id`, `name`, `version`, and `summary`
2803. Put the diagram in the body as a fenced `mermaid`, `plantuml`, or other supported diagram block
2814. Reference the diagram from related resources using the `diagrams` frontmatter field
282
283### Documenting a Business Flow
284
285When a user describes a multi-step process:
286
2871. Identify distinct steps (user actions, service calls, message exchanges, external systems)
2882. Generate the flow `index.mdx` with `steps` array
2893. Each step should have `id`, `title`, and appropriate type (`actor`, `service`, `agent`, `message`, `externalSystem`)
2904. Connect steps with `next_step` or `next_steps` for branching
291
292### Documenting Channel Routing
293
294When a user describes how messages flow through infrastructure:
295
2961. Generate channel `index.mdx` files with `routes` for channel-to-channel routing
2972. Update service or agent `sends`/`receives` with `to`/`from` fields pointing to channels
2983. The full picture should show: Service or agent sends → Channel → routes to → Channel → service or agent receives
299
300## Quality Checklist
301
302- Take your time to do this thoroughly
303- Quality is more important than speed
304- Do not skip validation steps
305
306Before delivering documentation to the user, verify every file against this checklist:
307
3081. Frontmatter has valid YAML between `---` delimiters
3092. `id` matches the folder name
3103. `version` is a valid semver string
3114. `summary` is concise and meaningful (not generic)
3125. Message relationships (`sends`/`receives`) include `id`
3136. Channel routing (`to`/`from`) references valid channel IDs
3147. Body includes `<NodeGraph />` for visualization when the resource has graph relationships
3158. Schema references point to real files
3169. Folder structure follows catalog conventions
31710. No duplicate resources (checked against existing catalog)
31811. 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`
31912. Every domain has at least one system, service, or agent — never create an empty domain
32013. Domain `systems`, `services`, and `agents` frontmatter lists every direct system, service, and agent that belongs to that domain
32114. Domain `entities`, `data-products`, `flows`, and `diagrams` frontmatter lists nested resources when present
32215. Every domain has a `ubiquitous-language.mdx` file with relevant domain terms extracted from services, agents, events, commands, entities, data products, and business processes
32316. ADRs have a valid status, date, decision makers when known, and `appliesTo` references for impacted resources
32417. System `scope`, relationship pointers, and actor directions are valid when systems are generated
32518. Data product contract files referenced in `outputs.contract.path` exist when generated
326
327## Troubleshooting
328
329### Messages Not Showing in Visualizer
330If generated events/commands don't appear in the service or agent node graph:
331- Verify the `sends`/`receives` arrays in the service or agent frontmatter reference the exact `id` of the message
332- Ensure the message has its own `index.mdx` file
333
334### Schema Not Rendering
335If `<Schema />` or `<SchemaViewer />` components show errors:
336- Verify `schemaPath` in frontmatter points to a file that exists alongside `index.mdx`
337- Check the schema file is valid JSON/Avro/Protobuf
338
339### Folder Structure Not Recognized
340If resources don't appear in EventCatalog:
341- Verify the file is named exactly `index.mdx` (not `INDEX.mdx` or `readme.md`)
342- Verify the folder is inside a recognized collection directory (`systems/`, `services/`, `agents/`, `events/`, `domains/`, etc.)
343
344### System Context Diagram Not Showing Actors or Relationships
345If `<ContextDiagram />` does not show expected system context:
346- Verify the system frontmatter has `relationships` or `actors`
347- Verify `relationships` point to valid system IDs and include useful `label` values
348- Verify actor `direction` is `inbound` or `outbound`
349- If viewing a domain context diagram, verify the domain `systems` frontmatter references the relevant systems
350
351### Channel Routing Not Visible
352If channel connections don't appear in the visualizer:
353- Verify the `routes` field in the channel frontmatter references valid channel IDs
354- Verify the `to`/`from` fields in service or agent sends/receives reference valid channel IDs