Back to Details

c4-to-eventcatalog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

C4 to EventCatalog

C4 转换为 EventCatalog

Overview

概述

Map a C4 model into EventCatalog resources without flattening architecture intent. Produce a reviewable 
.c4-eventcatalog-plan.md
first, then use 
catalog-documentation-creator
to generate or update the actual catalog files after the user approves the mapping.
将 C4 模型映射为 EventCatalog 资源，同时避免将架构意图扁平化。首先生成可审查的 
.c4-eventcatalog-plan.md
，然后在用户批准映射后，使用 
catalog-documentation-creator
生成或更新实际的 EventCatalog 目录文件。

Load References

加载参考资料

Always read 
references/c4-mapping.md
before mapping a C4 model.
When generating files, read the relevant 
../catalog-documentation-creator/references/
files:
  • domains.md
    , 
    services.md
    , 
    agents.md
  • events.md
    , 
    commands.md
    , 
    queries.md
  • channels.md
    , 
    containers.md
    , 
    flows.md
  • components.md
    for NodeGraph, Mermaid, wiki links, schemas, and MDX components
映射 C4 模型前，始终读取 
references/c4-mapping.md
。
生成文件时，读取相关的 
../catalog-documentation-creator/references/
文件：
  • domains.md
    、
    services.md
    、
    agents.md
  • events.md
    、
    commands.md
    、
    queries.md
  • channels.md
    、
    containers.md
    、
    flows.md
  • components.md
    ，用于处理 NodeGraph、Mermaid、wiki 链接、schema 和 MDX 组件

Workflow

工作流

Follow these phases in order.
按顺序执行以下阶段。

1. Locate inputs

1. 定位输入

Ask for the C4 source if it is not provided. Accept Structurizr DSL/JSON, C4-PlantUML, Mermaid C4, Markdown architecture docs, or image diagrams. Warn that source text is more reliable than image-only extraction.
Ask whether the user has an EventCatalog project. If yes, ask for the path and verify 
eventcatalog.config.js
or known resource directories. If no, note that scaffolding happens during handoff through 
catalog-documentation-creator
.
如果未提供 C4 源文件，则向用户索取。接受 Structurizr DSL/JSON、C4-PlantUML、Mermaid C4、Markdown 架构文档或图像图表。提醒用户，源文本比仅从图像中提取的信息更可靠。
询问用户是否已有 EventCatalog 项目。如果是，请用户提供路径，并验证 
eventcatalog.config.js
或已知的资源目录。如果不是，则说明将在通过 
catalog-documentation-creator
移交时完成项目脚手架搭建。

2. Inventory the existing catalog

2. 盘点现有目录

If a catalog exists, inspect it before proposing changes:
  • Detect flat vs domain-nested structure.
  • Record existing resource IDs, names, versions, owners, and relationships.
  • Note naming style, schema formats, owner conventions, badges, and use of domains.
  • Treat existing catalog resources not present in the C4 model as 
    investigate
    , not deletion candidates.
如果目录已存在，请在提出更改建议之前对其进行检查：
  • 检测扁平结构还是 domain 嵌套结构。
  • 记录现有资源 ID、名称、版本、负责人及其关系。
  • 记录命名风格、schema 格式、负责人约定、徽章和 domain 的使用方式。
  • 将 C4 模型中不存在的现有目录资源视为 
    investigate
    ，而不是删除候选项。

3. Parse the C4 model

3. 解析 C4 模型

Extract:
  • People and external systems
  • Software systems
  • Containers, including apps, services, agents, databases, queues, and browsers/mobile clients
  • Components only when they cross an ownership, deployment, data, or message boundary
  • Relationships, protocols, technologies, tags, descriptions, and views
  • Dynamic views or narrative scenarios that should become flows
  • Message names, topics, queues, APIs, commands, queries, events, and schema references
Preserve evidence. For source files, cite file paths and line numbers where possible. For diagrams, cite the diagram/view name and element IDs.
提取：
  • 人员与外部系统
  • 软件系统
  • 容器，包括应用、服务、Agent、数据库、队列以及浏览器或移动客户端
  • 仅当组件跨越所有权、部署、数据或消息边界时，才提取组件
  • 关系、协议、技术、标签、描述和视图
  • 应转换为 flow 的动态视图或叙述性场景
  • 消息名称、主题、队列、API、命令、查询、事件和 schema 引用
保留证据。对于源文件，尽可能引用文件路径和行号。对于图表，引用图表或视图名称以及元素 ID。

4. Map and reconcile

4. 映射与协调

Use 
references/c4-mapping.md
to map each C4 element into one of 
domain
, 
service
, 
agent
, 
event
, 
command
, 
query
, 
channel
, 
container
, 
flow
, 
external system only
, 
document inside resource body
, or 
needs user decision
.
For existing catalogs, assign each mapped item a status: 
new
, 
update
, 
unchanged
, or 
investigate
.
使用 
references/c4-mapping.md
，将每个 C4 元素映射为以下类别之一：
domain
、
service
、
agent
、
event
、
command
、
query
、
channel
、
container
、
flow
、
external system only
、
document inside resource body
或 
needs user decision
。
对于现有目录，为每个映射项指定状态：
new
、
update
、
unchanged
或 
investigate
。

5. Ask only structural questions

5. 仅询问结构性问题

Ask one question at a time. Each question must include:
  • The recommended answer
  • The evidence that led to it
  • The consequence for generated EventCatalog resources
Only ask about decisions that affect structure: domain boundaries, deployable service boundaries, agent classification, whether a relationship is an event/command/query/API call, whether an infrastructure node is a channel or data container, and whether to update an existing resource. Do not grill the user on prose, summaries, or cosmetic metadata.
每次只提出一个问题。每个问题必须包含：
  • 推荐答案
  • 得出该答案的证据
  • 对生成的 EventCatalog 资源产生的影响
仅询问会影响结构的决策：domain 边界、可部署服务边界、Agent 分类、关系属于 event、command、query 还是 API 调用、基础设施节点是 channel 还是数据容器，以及是否更新现有资源。不要就文案、摘要或外观元数据反复询问用户。

6. Write the plan

6. 编写计划

Write 
.c4-eventcatalog-plan.md
in the catalog directory when one exists, otherwise next to the supplied C4 source or in the current working directory. Include the template from 
references/c4-mapping.md
: source, decisions, resource mapping, relationships, files to create/update, and open questions.
Ask the user to approve the plan before generating catalog files.
如果目录已存在，则在目录中写入 
.c4-eventcatalog-plan.md
；否则将其放在所提供的 C4 源文件旁边或当前工作目录中。包含 
references/c4-mapping.md
中的模板：源文件、决策、资源映射、关系、要创建或更新的文件以及未决问题。
生成目录文件之前，请用户批准该计划。

7. Generate catalog files

7. 生成目录文件

After approval, use 
catalog-documentation-creator
to create or update files. Load only the relevant EventCatalog reference files for the resources in the approved plan. Follow the target catalog's existing structure and never overwrite an existing resource without preserving or reconciling user content.
获得批准后，使用 
catalog-documentation-creator
创建或更新文件。仅加载已批准计划中相关 EventCatalog 资源所对应的 EventCatalog 参考资料。遵循目标目录的现有结构，未经保留或协调用户内容，绝不覆盖现有资源。

Quality Rules

质量规则

  • Do not create one EventCatalog resource per C4 box by default. Map based on responsibility, deployment, ownership, message flow, and EventCatalog usefulness.
  • Do not create empty domains. A domain must contain at least one service or agent.
  • Do not model every C4 component as an EventCatalog resource. Most components belong in the parent service body, a Mermaid diagram, or a flow.
  • Prefer explicit C4 relationship labels over inferred message types. If the relationship label is ambiguous, mark it as 
    needs user decision
    .
  • Keep IDs consistent with the catalog. If creating a new catalog, prefer PascalCase resource IDs for business resources unless the user specifies otherwise.
  • Preserve existing catalog content. Add, update, or flag drift; do not delete.
  • Include 
    <NodeGraph />
    in generated resources through the handoff skill wherever the relevant EventCatalog reference recommends it.
  • 默认情况下，不要为每个 C4 方框创建一个 EventCatalog 资源。应根据职责、部署、所有权、消息流以及 EventCatalog 的实用性进行映射。
  • 不要创建空的 domain。一个 domain 必须至少包含一个 service 或 agent。
  • 不要将每个 C4 组件都建模为 EventCatalog 资源。大多数组件应归入父级 service 正文、Mermaid 图表或 flow。
  • 优先采用明确的 C4 关系标签，而不是推断消息类型。如果关系标签含义不明确，将其标记为 
    needs user decision
    。
  • 保持 ID 与目录一致。如果创建新目录，除非用户另有说明，否则业务资源优先使用 PascalCase 格式的 ID。
  • 保留现有目录内容。新增、更新或标记漂移；不要删除。
  • 在相关 EventCatalog 参考资料建议使用 
    <NodeGraph />
    的所有位置，通过交接 skill 在生成的资源中包含 
    <NodeGraph />
    。