Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

docs: document visual diagram architecture

tianma-if315bab0b3e7b
diff --git a/README.md b/README.md
index 3731deec..b1a0b92b 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ The iOS app requires an Apple ID from outside mainland China.
- **Seamless Dual-View Editor**: Switch effortlessly between intuitive rich text editing and Markdown source code on desktop.
- **Convenient Single-Note Export**: Export the current note directly as Markdown, HTML, or PDF for standalone storage, sharing, or publishing.
- **Native Mermaid Diagram Rendering**: Render clear flowcharts, sequence diagrams, and mind maps directly in notes, preserving clean, editable source code across Markdown and rich text views.
-- **Visual Diagram Notes**: Create and edit mind maps, flowcharts, and architecture diagrams on Web and desktop with semantic components, system boundaries, labeled connections, automatic layout, revision history, and PNG/SVG export. The Android and iOS apps preserve the same diagram data and render a semantic read-only view.
+- **Visual Diagram Notes**: Create and edit mind maps, flowcharts, and architecture diagrams on Web and desktop with semantic components, system boundaries, labeled connections, automatic layout, revision history, and PNG/SVG export. The Android and iOS apps preserve the same diagram data and render a semantic read-only view. See the [visual diagram notes design](docs/visual-diagram-notes.md).
- **Revision History**: Inspect and restore previous iterations of your notes with built-in version tracking.
- **Public Note Sharing**: Share a note publicly and stop sharing it at any time.
- **WeChat Article Clipping on Mobile**: Share a WeChat Official Account article to EdgeEver on your phone to extract its content and save it as an editable note.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 7af30211..86122075 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -60,7 +60,7 @@ iOS 客户端需要使用非中国大陆区 Apple ID 下载。
- **优雅的双视图编辑**:桌面端支持在富文本与 Markdown 源码视图之间自由切换。
- **单篇笔记便捷导出**:可将当前笔记直接导出为 Markdown、HTML 或 PDF,方便独立保存、分享与发布。
- **Mermaid 架构图与流程图渲染**:原生支持 Mermaid 代码块渲染,视图切换时完整保留可编辑源码,让绘制逻辑图表更直观。
-- **可视化图表笔记**:Web 与桌面端支持创建、编辑思维导图、流程图和架构图,提供语义组件、系统边界、连线说明、自动布局、历史版本及 PNG/SVG 导出;Android 与 iOS App 保留同一份图表数据,并提供语义化只读视图。
+- **可视化图表笔记**:Web 与桌面端支持创建、编辑思维导图、流程图和架构图,提供语义组件、系统边界、连线说明、自动布局、历史版本及 PNG/SVG 导出;Android 与 iOS App 保留同一份图表数据,并提供语义化只读视图。详见[可视化图表笔记设计说明](docs/visual-diagram-notes.zh-CN.md)。
- **笔记历史版本回溯**:自动记录修改历史,随时查阅与还原过往版本。
- **公开笔记分享**:支持公开分享笔记,并可随时取消分享。
- **移动 App 微信公众号文章剪藏**:在手机上将微信公众号文章分享至 EdgeEver,即可提取正文并保存为可继续编辑的笔记。
diff --git a/docs/visual-diagram-notes.md b/docs/visual-diagram-notes.md
new file mode 100644
index 00000000..dae4fcbf
--- /dev/null
+++ b/docs/visual-diagram-notes.md
@@ -0,0 +1,99 @@
+# Visual Diagram Notes Design
+
+This document summarizes the product and technical decisions made while extending EdgeEver from mind maps and flowcharts to architecture diagrams. It serves as a reference for future development, review, and cross-platform work.
+
+## Why architecture diagram notes exist
+
+Mind maps express topic hierarchies, and flowcharts express steps and decisions. Complex systems also need to express component responsibilities, system boundaries, dependency directions, and data flows. An architecture diagram is therefore a distinct note type, not a flowchart whose nodes merely have different names.
+
+A component should be recognizable from its appearance. EdgeEver currently distinguishes clients, frontends, services, databases, object storage, queues, security components, external services, and system boundaries with dedicated icons, outlines, and accent colors instead of one shared rectangle.
+
+## What IR means
+
+IR stands for Intermediate Representation. It is the structured source of truth between user editing operations and a concrete rendering engine. It stores node and edge semantics, coordinates, and dimensions without binding the note to X6, Mermaid, or a platform UI.
+
+```text
+User operations → Diagram IR → X6 / Mermaid / exporters
+```
+
+This abstraction provides three immediate benefits:
+
+- The same diagram can be rendered by different engines on different platforms.
+- Visual, layout, or rendering-library changes do not require migrating the note's meaning.
+- Data can be validated before rendering, rejecting dangling edges, invalid containment, and unsupported node types.
+
+The original mind-map and flowchart notes already use IR v1. Architecture diagrams use IR v2, adding semantic components, system boundaries, connection types, and bidirectional relationships.
+
+## IR and rendering-engine decoupling
+
+One of the IR's central benefits is preserving EdgeEver's freedom to choose its underlying rendering engines. The IR answers “what does this diagram mean?”, while an adapter answers “how does this engine draw it?”:
+
+```text
+ ┌→ X6 Adapter → Web / desktop interactive editing
+Diagram IR ────────┼→ Mermaid Adapter → Android / iOS viewing
+ ├→ Export Adapter → SVG / PNG
+ └→ MCP Tools → AI reading and modification
+```
+
+This separation does not erase differences between engines. Node coordinates, dimensions, containment, and connection directions still carry layout meaning, and renderers may support different capabilities. Explicit adapters isolate those differences instead of pretending that all engines are equivalent.
+
+The IR should contain stable business semantics and necessary layout facts, such as “this is a database,” “it belongs to the backend boundary,” and “a service accesses it through a data connection.” X6 SVG paths, internal events, view instances, and temporary selection state must stay out of the IR; otherwise engine coupling has merely moved into the persisted format.
+
+## Current data model
+
+A node contains `id`, `label`, `x`, `y`, `width`, `height`, and `shape`; a node inside a system boundary also has `parentId`. An edge contains `source` and `target`, with optional `label`, `kind`, and `bidirectional` fields.
+
+A diagram is stored as portable Markdown. Its body contains a Mermaid fallback, while a trailing `edgeever-diagram-v1` comment carries the Base64URL-encoded JSON IR. Mermaid keeps the note readable in clients without the interactive editor, while the embedded IR preserves lossless editing when the note is reopened.
+
+IR parsing and validation live in [`packages/shared/src/diagram.ts`](../packages/shared/src/diagram.ts), so Web, Android, and iOS do not maintain competing interpretations of the format.
+
+## Why EdgeEver continues to use AntV X6
+
+EdgeEver already has selection, dragging, zooming, connections, undo and redo, keyboard controls, automatic layout, revision history, and PNG/SVG export built around AntV X6. Architecture diagrams need semantic modeling and custom visuals on top of that mature interaction layer, not another canvas core.
+
+The reference project is most valuable for its product modeling and Typed IR ideas. Copying another drawing engine would also import its state management, coordinate system, interaction conventions, and data format, leaving EdgeEver with two canvas engines to maintain. Reusing X6 lets all three diagram types share infrastructure while development focuses on EdgeEver's own semantics and experience.
+
+This does not mean rendering every component as the same X6 node. X6 is only the underlying engine; component icons, SVG markup, shapes, ports, colors, boundaries, and connection semantics are customized by EdgeEver.
+
+## Cross-platform rendering boundary
+
+| Platform | Capability | Rendering path |
+| --- | --- | --- |
+| Web / PWA / desktop | Create, edit, auto-layout, revision history, and PNG/SVG export | IR → AntV X6 |
+| Android app | Semantic read-only view with complete IR preservation | IR → Mermaid → native note WebView |
+| iOS app | Semantic read-only view with complete IR preservation | IR → Mermaid → WKWebView |
+
+The native apps currently hide regular rich-text editing, double-tap editing, and AI rewriting for visual diagram notes. Those paths cannot represent diagram IR and could overwrite a structured diagram with plain text. Users can read, sync, share, and inspect history in the apps, while editing remains available on Web and desktop.
+
+## Agreed design principles
+
+- Diagram semantics belong to the IR; the rendering engine is not the data source.
+- Architecture components must communicate their purpose visually; names are supplementary.
+- A system boundary is a containment relationship, not a normal connectable business node.
+- Web and native apps consume the same persisted data rather than platform-specific diagram copies.
+- New versions should keep old diagrams readable, with format evolution managed explicitly through `schemaVersion`.
+- Native apps remain read-only until a touch editor can safely read and write the same IR.
+
+## MCP and AI-generated diagrams
+
+For MCP and AI, the IR is a positive capability and the foundation of a stable tool protocol. An AI can work with semantic IR instead of producing X6 internals, SVG, or an entire Mermaid document. It can therefore perform a local request such as “add a Redis cache between the API and database” while preserving the user's other nodes and layout decisions.
+
+MCP should expose small, explicit operations such as reading a diagram, adding or updating a node, connecting components, moving a node into a boundary, validating changes, and applying layout. It should not rely solely on a high-risk `replace_diagram_ir` operation. The recommended flow is:
+
+```text
+Read IR
+ → AI produces incremental operations
+ → server validates types, references, and containment
+ → produce a change preview
+ → user confirms
+ → apply operations and deterministic layout
+ → save a new revision
+```
+
+To reduce model context and accidental changes, the IR can evolve toward separate semantic, layout, and presentation concerns. AI should modify semantics by default, with deterministic layout algorithms handling coordinates. Layout or presentation should change only when the user explicitly requests it.
+
+An IR can still become a liability if it mirrors X6 too closely, lacks useful semantics, changes versions frequently, or lets AI overwrite a whole diagram without validation. The schema should therefore remain small, stable, versioned, validated, and friendly to incremental operations.
+
+## Future direction
+
+Full native editing should continue to use the same IR and separately address touch selection, dragging, connections, zooming, keyboard avoidance, and large-diagram performance. Whether that editor uses X6 in a WebView or a native canvas should be decided through prototypes and performance testing without changing the persisted format.
diff --git a/docs/visual-diagram-notes.zh-CN.md b/docs/visual-diagram-notes.zh-CN.md
new file mode 100644
index 00000000..cd42bd97
--- /dev/null
+++ b/docs/visual-diagram-notes.zh-CN.md
@@ -0,0 +1,99 @@
+# 可视化图表笔记设计说明
+
+本文简要记录 EdgeEver 从思维导图、流程图扩展到架构图时形成的产品与技术决策,供后续开发、评审和跨端适配参考。
+
+## 为什么需要架构图笔记
+
+思维导图适合表达主题层级,流程图适合表达步骤和判断,但复杂系统还需要表达组件职责、系统边界、依赖方向和数据流。因此,架构图不是把流程图节点换个名称,而是一种具有独立语义的笔记类型。
+
+架构图组件必须能通过外观被快速识别。当前支持客户端、前端、服务、数据库、对象存储、消息队列、安全组件、外部服务和系统边界;它们分别使用不同图标、轮廓和强调色,而不是共用同一种矩形节点。
+
+## IR 是什么
+
+IR(Intermediate Representation,中间表示)是图表的结构化事实来源,位于“用户编辑操作”和“具体渲染引擎”之间。它保存节点、连线、坐标、尺寸和语义,但不绑定 X6、Mermaid 或某个平台 UI。
+
+```text
+用户操作 → Diagram IR → X6 / Mermaid / 导出器
+```
+
+这层抽象带来三个直接收益:
+
+- 同一份图表可以在不同端由不同引擎渲染。
+- 更换外观、布局或渲染库时,不需要迁移笔记的业务含义。
+- 数据可以先验证再渲染,避免悬空连线、非法父子关系和错误节点类型进入编辑器。
+
+原有思维导图和流程图已经使用 IR v1;架构图在此基础上使用 IR v2,增加语义组件、系统边界、连线类型和双向关系。
+
+## IR 与绘图引擎解耦
+
+IR 的核心价值之一,是让 EdgeEver 保留对底层绘图引擎的选择权。IR 负责回答“这张图表达什么”,适配器负责回答“当前引擎如何把它画出来”:
+
+```text
+ ┌→ X6 Adapter → Web / 桌面交互编辑
+Diagram IR ────────┼→ Mermaid Adapter → Android / iOS 阅读
+ ├→ Export Adapter → SVG / PNG
+ └→ MCP Tools → AI 读取与修改
+```
+
+这种解耦并不代表不同引擎之间不存在差异。节点坐标、尺寸、容器关系和连线方向仍具有布局含义,各渲染器也可能支持不同能力,因此需要明确的适配层。目标是隔离差异,而不是假设所有引擎完全等价。
+
+IR 中应保存稳定的业务语义和必要布局,例如“这是数据库”“它位于后端边界中”“服务通过数据连接访问它”。X6 的 SVG Path、内部事件、视图实例、临时选择状态等引擎细节不应进入 IR,否则只是把强耦合转移到了持久化格式中。
+
+## 当前数据模型
+
+节点包含 `id`、`label`、`x`、`y`、`width`、`height`、`shape`,位于系统边界中的节点还包含 `parentId`。连线包含 `source`、`target`,并可携带 `label`、`kind` 和 `bidirectional`。
+
+图表保存为一份可移植 Markdown:正文包含 Mermaid 降级视图,末尾的 `edgeever-diagram-v1` 注释保存 Base64URL 编码的 JSON IR。Mermaid 让不具备交互编辑器的客户端仍可阅读,注释中的 IR 则保证再次打开时可以无损编辑。
+
+IR 的实现和校验集中在 [`packages/shared/src/diagram.ts`](../packages/shared/src/diagram.ts),避免 Web、Android 和 iOS 各自解释一套格式。
+
+## 为什么继续使用 AntV X6
+
+EdgeEver 已经围绕 AntV X6 建立了选择、拖拽、缩放、连线、撤销重做、键盘操作、自动布局、历史版本和 PNG/SVG 导出链路。架构图需要的是在这套成熟交互能力上增加语义模型与定制视觉,而不是重新实现一个画布内核。
+
+参考项目的价值主要在产品建模和 Typed IR 思路。直接照搬另一套绘图引擎会同时引入其状态管理、坐标体系、交互约定和数据格式,并造成两套画布引擎长期并存。继续复用 X6 可以让三种图表共享基础设施,把开发投入集中在 EdgeEver 自己的语义组件和用户体验上。
+
+这并不意味着把所有组件画成同一种 X6 节点。X6 只是底层引擎;组件图标、SVG 标记、形状、端口、配色、边界和连线语义均由 EdgeEver 定制。
+
+## 跨端渲染边界
+
+| 平台 | 能力 | 渲染路径 |
+| --- | --- | --- |
+| Web / PWA / 桌面端 | 创建、编辑、自动布局、历史版本、PNG/SVG 导出 | IR → AntV X6 |
+| Android App | 语义化只读查看,完整保留 IR | IR → Mermaid → 原生笔记 WebView |
+| iOS App | 语义化只读查看,完整保留 IR | IR → Mermaid → WKWebView |
+
+原生 App 暂不开放普通富文本编辑、双击编辑或 AI 改写入口,因为这些路径无法表达图表 IR,可能把结构化图表覆盖成普通文本。用户可在 App 中阅读、同步、分享和查看历史版本,在 Web 或桌面端完成图表编辑。
+
+## 已确定的设计原则
+
+- 图表语义由 IR 决定,渲染引擎不是数据源。
+- 架构组件必须“看外观就知道用途”,名称只是补充。
+- 系统边界是容器关系,不是可连线的普通业务节点。
+- Web 与原生 App 使用同一份持久化数据,不维护平台专属图表副本。
+- 新版本优先保持旧图可读;格式演进通过 `schemaVersion` 明确管理。
+- 在原生触控编辑器能够安全读写同一 IR 之前,App 保持只读。
+
+## MCP 与 AI 生成图表
+
+对于 MCP 和 AI,IR 是正向能力,也是稳定的工具协议基础。AI 面向语义化 IR 工作,不必生成 X6 内部配置、SVG 或整张 Mermaid 源码,因此可以理解和执行“在 API 与数据库之间增加 Redis 缓存”这类局部修改,同时保留用户已经调整好的其他节点和布局。
+
+MCP 应优先暴露小而明确的操作,例如读取图表、增加或更新节点、连接组件、移动到系统边界、校验变更和应用布局,而不是只提供一个高风险的 `replace_diagram_ir`。推荐流程是:
+
+```text
+读取 IR
+ → AI 生成增量操作
+ → 服务端校验类型、引用和容器关系
+ → 生成变更预览
+ → 用户确认
+ → 应用操作并自动布局
+ → 保存为新的历史版本
+```
+
+为了降低模型上下文和误修改风险,后续可将 IR 的关注点进一步分为语义层、布局层和呈现层。AI 默认修改语义层,确定性的布局算法负责坐标;只有用户明确要求调整位置或外观时,才修改布局层或呈现层。
+
+IR 也可能产生负担:如果格式过度贴近 X6、语义过少、版本频繁变化,或者允许 AI 不经校验地覆盖整张图,它就会成为新的耦合点。因此,Schema 应保持小而稳定、可版本化、可校验,并支持增量操作。
+
+## 后续演进方向
+
+如果要实现原生 App 完整编辑,应继续复用同一 IR,并单独设计触控选择、拖拽、连线、缩放、键盘避让和大图性能。是否复用 X6 WebView 或开发原生画布,应通过原型和性能测试决定,而不应改变已保存的数据格式。