AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.
HTML ai-agentcloudflarecloudflare-d1cloudflare-r2cloudflare-workersdockerelectronevernoteevernote-alternativeknowledge-basemcpnote-takingobsidian-alternativeoffline-firstpersonal-knowledge-basepwaself-hostedsqlitetiptapweb-clipper
docs(diagram): reframe design notes around IR and X6 selection
tianma-if16da051127e5
diff --git a/docs/visual-diagram-notes.md b/docs/visual-diagram-notes.mdindex d5378bb5..663e520a 100644--- a/docs/visual-diagram-notes.md+++ b/docs/visual-diagram-notes.md@@ -1,12 +1,6 @@# 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.+This document records the technical choices and design decisions behind EdgeEver visual diagram notes (mind maps, flowcharts, and architecture diagrams). It is a reference for future development, review, and cross-platform work.## What IR means@@ -49,13 +43,15 @@ User-authored ` ```mermaid ` code blocks in ordinary rich-text notes are a separIR 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+## Why AntV X6++Visual diagram notes need an editable canvas: selection, dragging, zooming, connections, undo and redo, keyboard controls, automatic layout, and PNG/SVG export. AntV X6 supplies that canvas kernel; it is not the product model for any one diagram type. Mind maps, flowcharts, and architecture diagrams share the same engine. Their differences live in IR semantics and EdgeEver's node and edge customization.-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. Android and iOS now use the same X6 adapter for read-only viewing (`diagramDocumentToX6Cells` plus a non-interactive `Graph`), so first-party canvases no longer split between X6 on Web and Mermaid on mobile.+The IR answers “what does this diagram mean?”; the X6 adapter answers “how do we draw it and let the user edit it?” X6 internals, coordinate conventions, and view instances therefore stay out of the persisted format. Adopting a second engine for one diagram type would also import another state manager, coordinate system, interaction model, and data format, leaving two canvases to maintain.-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.+Android and iOS read-only viewers reuse the same X6 adapter (`diagramDocumentToX6Cells` plus a non-interactive `Graph`). First-party canvases no longer split between X6 on Web and Mermaid on mobile. Mermaid remains the portable envelope, the renderer for embedded rich-text diagrams, and the fallback when IR parsing fails.-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.+This does not mean rendering every node as the same X6 rectangle. X6 is only the underlying engine; icons, SVG markup, shapes, ports, colors, boundaries, and connection semantics are customized by EdgeEver per diagram type.## Cross-platform rendering boundarydiff --git a/docs/visual-diagram-notes.zh-CN.md b/docs/visual-diagram-notes.zh-CN.mdindex c4a881b3..da0dd767 100644--- a/docs/visual-diagram-notes.zh-CN.md+++ b/docs/visual-diagram-notes.zh-CN.md@@ -1,12 +1,6 @@# 可视化图表笔记设计说明-本文简要记录 EdgeEver 从思维导图、流程图扩展到架构图时形成的产品与技术决策,供后续开发、评审和跨端适配参考。--## 为什么需要架构图笔记--思维导图适合表达主题层级,流程图适合表达步骤和判断,但复杂系统还需要表达组件职责、系统边界、依赖方向和数据流。因此,架构图不是把流程图节点换个名称,而是一种具有独立语义的笔记类型。--架构图组件必须能通过外观被快速识别。当前支持客户端、前端、服务、数据库、对象存储、消息队列、安全组件、外部服务和系统边界;它们分别使用不同图标、轮廓和强调色,而不是共用同一种矩形节点。+本文记录 EdgeEver 可视化图表笔记(思维导图、流程图、架构图)的技术选型与方案决策,供后续开发、评审和跨端适配参考。## IR 是什么@@ -49,13 +43,15 @@ IR 中应保存稳定的业务语义和必要布局,例如“这是数据库IR 的实现和校验集中在 [`packages/shared/src/diagram.ts`](../packages/shared/src/diagram.ts),避免 Web、Android 和 iOS 各自解释一套格式。-## 为什么继续使用 AntV X6+## 为什么使用 AntV X6++可视化图表笔记需要一块可编辑画布:选择、拖拽、缩放、连线、撤销重做、键盘操作、自动布局和 PNG/SVG 导出。AntV X6 提供的是这套画布内核,而不是某一种图表类型的产品模型。思维导图、流程图和架构图共用同一引擎,差异落在 IR 语义和 EdgeEver 的节点、连线定制上。-EdgeEver 已经围绕 AntV X6 建立了选择、拖拽、缩放、连线、撤销重做、键盘操作、自动布局、历史版本和 PNG/SVG 导出链路。架构图需要的是在这套成熟交互能力上增加语义模型与定制视觉,而不是重新实现一个画布内核。Android 与 iOS 的只读查看也已复用同一套 X6 适配器(`diagramDocumentToX6Cells` 加不可交互的 `Graph`),自有客户端画布不再按「Web 用 X6、移动端用 Mermaid」分轨。+IR 负责回答“这张图表达什么”,X6 适配器负责回答“当前如何把它画出来并让用户改”。因此不把 X6 内部状态、坐标约定或视图实例写进持久化格式。如果为某一类图表另选引擎,会同时引入另一套状态管理、坐标体系、交互约定和数据格式,并让两套画布长期并存。-参考项目的价值主要在产品建模和 Typed IR 思路。直接照搬另一套绘图引擎会同时引入其状态管理、坐标体系、交互约定和数据格式,并造成两套画布引擎长期并存。继续复用 X6 可以让三种图表共享基础设施,把开发投入集中在 EdgeEver 自己的语义组件和用户体验上。+Android 与 iOS 的只读查看也复用同一套 X6 适配器(`diagramDocumentToX6Cells` 加不可交互的 `Graph`)。自有客户端画布不再按「Web 用 X6、移动端用 Mermaid」分轨。Mermaid 仍用于可移植信封、富文本嵌入图表,以及 IR 解析失败时的降级。-这并不意味着把所有组件画成同一种 X6 节点。X6 只是底层引擎;组件图标、SVG 标记、形状、端口、配色、边界和连线语义均由 EdgeEver 定制。+这并不意味着把所有节点画成同一种 X6 矩形。X6 只是底层引擎;图标、SVG 标记、形状、端口、配色、边界和连线语义均由 EdgeEver 按图表类型定制。## 跨端渲染边界