pma-draw

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ReactFlow Diagram Creator

ReactFlow图表生成器

Generate

.rfd.json

files that encode meaning in shape, position, and connection — consumed by a ReactFlow-based viewer (pma-viewer) with a predefined catalog of custom node types.

Keep this entry file small. Load only the references needed for the current diagram.

生成以形状、位置和连接来编码语义的.rfd.json文件，供基于ReactFlow的查看器（pma-viewer）使用，该查看器拥有预定义的自定义节点类型目录。

保持入口文件精简，仅加载当前图表所需的引用资源。

Always-On Rules

通用规则

Isomorphism first: node layout and edge topology must mirror the concept's structure. If removing all labels still communicates the idea, the design is right.
Use predefined node types only. Pull every node
```
type
```
from
```
references/node-types.md
```
. Never invent new types unless the user asks and the viewer supports them.
Use predefined edge types only. Pull every edge
```
type
```
from
```
references/edges.md
```
. Avoid raw
```
default
```
unless no preset fits.
Colors come from
references/colors.md
. Node styling is driven by the preset; override only when semantics require it.
Grouping via parent-child, not by drawing a container rectangle. Use
```
parentNode
```
+
```
extent: "parent"
```
on child nodes and a
```
group
```
type parent.
Every relationship needs an edge. Proximity alone is not a connection.
No local render: the skill emits
```
.rfd.json
```
only. Rendering and export happen in pma-viewer (SPA). Quality must be enforced at JSON level — see
```
references/validation.md
```
.
Build large diagrams section-by-section. Append nodes/edges per edit, namespace IDs by section prefix (
```
ingest__
```
,
```
process__
```
,
```
deliver__
```
) to keep cross-section references readable.

同构优先：节点布局和边拓扑必须与概念结构一致。如果移除所有标签仍能传达核心思想，说明设计是合理的。
仅使用预定义节点类型：所有节点
```
type
```
均来自
```
references/node-types.md
```
。除非用户明确要求且查看器支持，否则不得创建新类型。
仅使用预定义边类型：所有边
```
type
```
均来自
```
references/edges.md
```
。除非没有合适的预设，否则避免使用原生
```
default
```
类型。
颜色取自
references/colors.md
：节点样式由预设驱动，仅在语义需要时才进行覆盖。
通过父子关系分组，而非绘制容器矩形。对子节点使用
```
parentNode
```
+
```
extent: "parent"
```
配置，并使用
```
group
```
类型的父节点。
每个关系都需要一条边：仅靠位置接近不代表存在连接。
不支持本地渲染：本工具仅输出.rfd.json文件。渲染和导出操作在pma-viewer（SPA）中完成。必须在JSON层面保证质量——详见
```
references/validation.md
```
。
分模块构建大型图表：每次编辑添加节点/边，通过为ID添加模块前缀（如
```
ingest__
```
、
```
process__
```
、
```
deliver__
```
），使跨模块引用更易读。

Core Workflow

核心工作流程

Step 1: Depth Assessment

步骤1：复杂度评估

Simple / Conceptual — abstract node types (
```
process
```
,
```
start
```
,
```
end
```
), generic edges. For mental models and philosophies.
Comprehensive / Technical — semantic node types (
```
backend
```
,
```
database
```
,
```
queue
```
,
```
ai
```
),
```
evidence
```
nodes with real code/JSON, typed edges (
```
stream
```
,
```
callback
```
). For real systems, protocols, tutorials.

Technical diagrams require research: look up actual specs, endpoints, event names, and data formats before writing JSON.

简单/概念型——使用抽象节点类型（
```
process
```
、
```
start
```
、
```
end
```
）和通用边，适用于心智模型和理念展示。
全面/技术型——使用语义化节点类型（
```
backend
```
、
```
database
```
、
```
queue
```
、
```
ai
```
）、包含真实代码/JSON的
```
evidence
```
节点，以及带类型的边（
```
stream
```
、
```
callback
```
），适用于真实系统、协议和教程。

技术型图表需要调研：在编写JSON前，需查阅实际规范、端点、事件名称和数据格式。

Step 2: Concept-to-Pattern Mapping

步骤2：概念到模式映射

For each major concept pick the visual pattern that mirrors its behavior — fan-out, convergence, tree, timeline, cycle, assembly line, side-by-side, gap, cloud. No two major concepts should share the same pattern. Details in

references/design.md

为每个核心概念选择与其行为匹配的视觉模式——扇出、汇聚、树形、时间线、循环、流水线、并排、间隔、云。任意两个核心概念不应使用相同模式。详情见

references/design.md

。

Step 3: Layout Planning

步骤3：布局规划

Pick a layout template from

references/layouts.md

(vertical-flow, horizontal-pipeline, hub-and-spoke, swimlanes, timeline, matrix). Compute a grid of

position

values before emitting nodes. ReactFlow uses absolute pixel positions — consistency comes from a shared grid, not from an auto-layout pass.

从

references/layouts.md

中选择布局模板（垂直流、水平流水线、中心辐射、泳道、时间线、矩阵）。在输出节点前计算

position

值的网格。ReactFlow使用绝对像素位置——一致性来自共享网格，而非自动布局。

Step 4: Pick Node & Edge Types

步骤4：选择节点与边类型

Each discovered component → pick a node
```
type
```
from the catalog.
Each relationship → pick an edge
```
type
```
that matches its semantics (flow, stream, callback, dependency, comparison).
For technical diagrams, add
```
evidence
```
nodes for real code snippets or data payloads.

每个已识别的组件→从目录中选择对应的节点
```
type
```
。
每个关系→选择与其语义匹配的边
```
type
```
（flow、stream、callback、dependency、comparison）。
对于技术型图表，添加包含真实代码片段或数据负载的
```
evidence
```
节点。

Step 5: Emit JSON

步骤5：输出JSON

Write the wrapper +

nodes[]

edges[]

viewport

. Use predefined templates from

references/templates.md

as starting points. Keep IDs descriptive (

api-server

edge__api-to-db

编写包装结构 +

nodes[]

edges[]

viewport

。以

references/templates.md

中的预定义模板为起点。使用描述性ID（如

api-server

、

edge__api-to-db

）。

Step 6: Validate & Hand Off

步骤6：验证与交付

Run the pre-flight checklist in

references/validation.md

(IDs unique, edges reference existing nodes,

parentNode

refs valid,

sourceHandle

targetHandle

match node contracts, no position collisions). Then tell the user to open the file in pma-viewer (see

references/render.md

). The agent cannot see the rendered result, so JSON-level discipline is mandatory.

执行

references/validation.md

中的预检清单（ID唯一、边引用存在的节点、

parentNode

引用有效、

sourceHandle

targetHandle

匹配节点约定、无位置冲突）。然后告知用户在pma-viewer中打开文件（详见

references/render.md

）。本工具无法查看渲染结果，因此必须严格遵守JSON层面的规范。

Section-by-Section for Large Diagrams

大型图表的分模块构建

Write the wrapper (
```
schema
```
,
```
type
```
,
```
viewport
```
,
```
metadata
```
) and Section 1's
```
nodes
```
+
```
edges
```
.
Append one section per edit. Prefix IDs by section (
```
ingest__source
```
,
```
ingest__queue
```
) to keep later cross-section edges readable.
When a new section's edge targets an earlier node, cite the exact existing node ID from the previous section.
Namespace positions by section: reserve columns (
```
x
```
) or rows (
```
y
```
) per section so later edits don't collide with earlier ones.
After all sections exist, re-read the full file once to check edge references and position overlaps before handing off.

Do not generate an entire comprehensive diagram in one response, hand-write a generator script, or delegate JSON emission to a coding sub-agent — each path produces worse output than section-by-section edits.

编写包装结构（
```
schema
```
、
```
type
```
、
```
viewport
```
、
```
metadata
```
）以及第1模块的
```
nodes
```
+
```
edges
```
。
每次编辑添加一个模块。为ID添加模块前缀（如
```
ingest__source
```
、
```
ingest__queue
```
），使后续跨模块边引用更易读。
当新模块的边指向早期节点时，需引用前一模块中该节点的确切ID。
为模块划分位置命名空间：为每个模块预留列（
```
x
```
）或行（
```
y
```
），避免后续编辑与早期内容冲突。
所有模块完成后，重新通读整个文件，检查边引用和位置重叠，再交付给用户。

请勿一次性生成完整的全面型图表、手写生成脚本或委托编码子代理输出JSON——这些方式的输出质量均不如分模块编辑。

Output

输出

File:
```
docs/architecture/<name>.rfd.json
```
by default, or a path the user specifies. Extension
```
.rfd.json
```
marks the ReactFlow Diagram schema and keeps plain JSON tooling compatibility.
Viewing: open in pma-viewer (ReactFlow-based SPA). PNG / SVG export and editing are handled there —
```
references/render.md
```
covers the handoff.
Embedding: four paths in
```
references/integration.md
```
:
- React / MDX sites →
```
<PmaViewer src="..." />
```
  component
- Plain HTML →
```
pma-viewer
```
  UMD
```
<script>
```
  +
```
PmaViewer.mount(...)
```
- Interactive link → hosted viewer with
```
?src=<url>
```
  query param
- Static image (GitHub README, email, PDF) →
```
GET /render.svg?src=<url>
```
  server-rendered SVG endpoint

文件：默认路径为
```
docs/architecture/<name>.rfd.json
```
，或用户指定的路径。
```
.rfd.json
```
扩展名标记该文件遵循ReactFlow图表 Schema，同时保持与普通JSON工具的兼容性。
查看：在基于ReactFlow的SPA——pma-viewer中打开。PNG/SVG导出和编辑操作在该工具中完成——
```
references/render.md
```
涵盖交付说明。
嵌入：
```
references/integration.md
```
中提供四种方式：
- React / MDX 站点→使用
```
<PmaViewer src="..." />
```
  组件
- 纯HTML→引入
```
pma-viewer
```
  UMD
```
<script>
```
  + 调用
```
PmaViewer.mount(...)
```
- 交互式链接→通过托管查看器的
```
?src=<url>
```
  查询参数加载
- 静态图片（GitHub README、邮件、PDF）→使用
```
GET /render.svg?src=<url>
```
  服务端渲染SVG端点

Reference Packs

参考资源包

```
references/design.md
```
Visual pattern library, evidence artifacts, multi-zoom architecture, concept-to-pattern mapping.

references/json-schema.md

File wrapper,

nodes

edges

viewport

structure,

parentNode

grouping rules, handles.

```
references/node-types.md
```
Preset custom node catalog with data-schema per type. Semantic, structural, and utility categories.
```
references/edges.md
```
Preset edge catalog: flow, stream, callback, dependency, comparison, annotated. Handle positions, animation, labels.
```
references/colors.md
```
Semantic color palette (default / AWS / Azure / GCP / K8s) and text hierarchy. Styled presets in node-types reference this file.
```
references/layouts.md
```
Layout templates (vertical flow, horizontal pipeline, hub-and-spoke, swimlanes, timeline, matrix) with grid math.
```
references/templates.md
```
Copy-paste node / edge JSON and full starter diagrams (3-tier, microservices, event-driven, data pipeline, CI/CD).
```
references/validation.md
```
Pre-flight algorithm, checklists, common bug recipes.
```
references/render.md
```
pma-viewer SPA contract, handoff format, in-viewer export, troubleshooting.
```
references/integration.md
```
How downstream consumers embed the diagram: MDX / React component, browser
```
<script>
```
SDK, URL-loaded JSON with the hosted viewer, and server-rendered SVG endpoint (for GitHub READMEs, email, PDFs).

```
references/design.md
```
视觉模式库、证据工件、多缩放架构、概念到模式映射。
```
references/json-schema.md
```
文件包装结构、
```
nodes
```
/
```
edges
```
/
```
viewport
```
结构、
```
parentNode
```
分组规则、句柄配置。
```
references/node-types.md
```
预设自定义节点目录，包含每种类型的数据Schema，分为语义、结构和工具类。
```
references/edges.md
```
预设边目录：flow、stream、callback、dependency、comparison、annotated。包含句柄位置、动画、标签配置。
```
references/colors.md
```
语义调色板（默认/AWS/Azure/GCP/K8s）和文本层级。节点类型引用中的样式预设均基于此文件。
```
references/layouts.md
```
布局模板（垂直流、水平流水线、中心辐射、泳道、时间线、矩阵）及网格计算方法。
```
references/templates.md
```
可直接复制的节点/边JSON片段和完整入门图表（三层架构、微服务、事件驱动、数据流水线、CI/CD）。
```
references/validation.md
```
预检算法、检查清单、常见错误示例。
```
references/render.md
```
pma-viewer SPA约定、交付格式、查看器内导出功能、故障排查。
```
references/integration.md
```
下游消费者嵌入图表的方式：MDX/React组件、浏览器
```
<script>
```
SDK、通过URL加载JSON的托管查看器、服务端渲染SVG端点（适用于GitHub README、邮件、PDF）。

Quick Routing

快速指引

Designing from scratch: load

references/design.md

, then

references/layouts.md

Picking node / edge types: load

references/node-types.md

references/edges.md

Writing JSON: load

references/json-schema.md

references/templates.md

Codebase-to-architecture extraction: load

references/node-types.md

references/layouts.md

Validating before delivery: load
```
references/validation.md
```
.
Telling the user how to open or export in pma-viewer: load
```
references/render.md
```
.
Embedding the diagram in docs (MDX / HTML / README / SVG): load
```
references/integration.md
```
.

If the project also uses

/pma

for workflow control, load

/pma

first, then

/pma-draw

only when a diagram is required.

从零开始设计：加载
```
references/design.md
```
，再加载
```
references/layouts.md
```
。

选择节点/边类型：加载

references/node-types.md

references/edges.md

。

编写JSON：加载

references/json-schema.md

references/templates.md

。

从代码库提取架构：加载

references/node-types.md

references/layouts.md

。

交付前验证：加载
```
references/validation.md
```
。
告知用户如何在pma-viewer中打开或导出：加载
```
references/render.md
```
。
在文档中嵌入图表（MDX/HTML/README/SVG）：加载
```
references/integration.md
```
。

如果项目同时使用

/pma

进行工作流控制，请先加载

/pma

，仅当需要图表时再加载

/pma-draw

。