Skip to content

CanvasAnvil is an open source AI diagram maker and flowchart generator - an infinite-canvas diagram editor and self-hosted drawio alternative that writes editable .drawio files. Text to diagram, then fix nodes, layout and labels in place. Also AI presentations, interior design CAD/BOM, posters and infographics.

docs: describe the structure the refactor produced

codingFeng1019680fb111550
diff --git a/README.md b/README.md
index 7f02500..13bc8ca 100644
--- a/README.md
+++ b/README.md
@@ -181,12 +181,16 @@ npm run build
## 📝 Development Notes
-- AI configuration is read from local app settings; image-generation workflows use the configured image provider
-- Local development depends on the API service for routes such as `/api/ppt-ai`
-- After changing local API route wiring in `vite.config.ts`, restart the dev server
+- Every model call uses the OpenAI HTTP protocol. To use another vendor, point the base URL in Settings at their OpenAI-compatible endpoint — there is no provider list to pick from.
+- AI configuration is read from local app settings; the text and image channels are configured separately.
+- Local development depends on the API service for `/api/chat` and `/api/ppt-ai`.
+- After changing local API route wiring in `vite.config.ts`, restart the dev server.
+- `src/server/**` and `src/ai/**` use relative imports: `vite.config.ts` imports the API routes and Node resolves that file without the `@/` path alias.
+- Set `PROMPT_LOG_DIR` to write assembled prompts to disk; it is off by default because the log contains the user's content.
## 📚 Docs
+- Architecture overview: [docs/architecture.md](docs/architecture.md)
- Deployment guide: [deploy/README.md](deploy/README.md)
## ⚖️ License
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 05821a8..d39db6c 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -181,12 +181,16 @@ npm run build
## 📝 开发说明
-- AI 配置读取本地应用设置;生图工作流使用已配置的图片生成供应商
-- 本地开发依赖 API 服务提供 `/api/ppt-ai` 等接口
-- 修改 `vite.config.ts` 中的本地 API 路由后,需要重启开发服务
+- 所有模型调用都走 OpenAI 的 HTTP 协议。想换厂商,只要在设置里把 Base URL 指向它的 OpenAI 兼容端点即可,没有厂商列表可选。
+- AI 配置读取本地应用设置;文本通道和生图通道分别配置。
+- 本地开发依赖 API 服务提供 `/api/chat` 和 `/api/ppt-ai`。
+- 修改 `vite.config.ts` 中的本地 API 路由后,需要重启开发服务。
+- `src/server/**` 和 `src/ai/**` 使用相对路径导入:`vite.config.ts` 会 import API 路由,而 Node 加载这个配置文件时不认 `@/` 别名。
+- 设置 `PROMPT_LOG_DIR` 可把拼装好的提示词写入磁盘;默认关闭,因为日志里含有用户内容。
## 📚 文档
+- 架构说明:[docs/architecture.md](docs/architecture.md)
- 部署说明:[deploy/README.md](deploy/README.md)
## ⚖️ 许可证
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..50ce534
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,96 @@
+# Architecture
+
+CanvasAnvil is a Vite + React single-page app with a small Node API beside it.
+Three canvases — Flow, Interior Design (CAD), and PPT — share one shell, one UI
+kit, and one model client.
+
+## Layout
+
+```
+src/
+ app/ the shell: App, the workspace registry, error boundary
+ ai/ the model client — one OpenAI-compatible transport
+ shared/ everything more than one workspace uses
+ ui/ the shadcn component kit (one copy)
+ chat/ the chat components and plumbing the panels share
+ files/ upload extraction: PDF, Word, LaTeX archives, figures
+ storage/ the IndexedDB key/value store factory
+ i18n/ language setting and the app-shell dictionary
+ lib/ cn()
+ workspaces/ flow / cad / ppt — each canvas's own logic
+ features/ ppt-editor: the editable-slide bridge
+ pages/ the portal / landing page
+ server/ the API: routes, chat pipeline, telemetry
+ components/ the settings dialog
+api/ thin route shims plus the Express entry point
+agent/ system prompts, as markdown, loaded with ?raw
+skill/ the per-canvas skill bundles
+```
+
+## Rules the structure depends on
+
+**Nothing in `src/server/` imports from `src/workspaces/`.** The server is a
+separate program that happens to share a repository; a backend reaching into a
+frontend folder is what put the draw.io system prompt and the Langfuse client
+inside the Flow workspace for a while.
+
+**`src/ai/**` and `src/server/**` use relative imports, not the `@/` alias.**
+Vite loads `vite.config.ts` through plain Node, and that config imports the API
+route handlers — Node does not know about the tsconfig path alias.
+
+**Storage keys are load-bearing.** IndexedDB database names and localStorage
+keys carry users' saved work across releases. `src/workspaces/*/storage.ts` and
+`flow/next/lib/flow-storage-keys.ts` name them in one place each; renaming one
+orphans whatever was stored under the old name.
+
+## The model client
+
+Every model call speaks the OpenAI HTTP protocol:
+
+| Purpose | Route |
+| --- | --- |
+| Chat, vision, all text generation | `POST {baseUrl}/chat/completions` |
+| Image generation | `POST {baseUrl}/images/generations` |
+| Image editing, given a reference | `POST {baseUrl}/images/edits` |
+
+There is no provider list. Using a different vendor means pointing the base URL
+at their OpenAI-compatible endpoint in Settings.
+
+Image generation tries the images route first and falls back to
+`/chat/completions` with `image_url` parts, because a number of
+OpenAI-compatible gateways expose their image models as chat models. The
+fallback order is pinned by `tests/ai-request-shape.test.ts`.
+
+Two paths reach the model:
+
+- **`/api/ppt-ai`** — non-streaming, used by the CAD and PPT workspaces through
+ `src/ai/client.ts`. The browser never talks to the provider directly, so the
+ key stays out of cross-origin requests and the server can inline remote
+ images the browser could not fetch.
+- **`/api/chat`** — streaming with tool calls, used by Flow. Runs as a pipeline
+ whose stages live in `src/server/chat/`: validate, extract attachments,
+ summarise, classify intent, optionally draft a reference image, assemble the
+ prompt, stream.
+
+## Adding a canvas
+
+Add an entry to `WORKSPACES` in `src/app/workspaces.ts`. The header tabs, the
+persisted selection, and the rendered workspace all read from that array. Give
+the shell its own lazy import so it does not land in the initial bundle.
+
+## Bundle
+
+The entry chunk holds the shell only. Each workspace, and the heavy
+dependencies (`pptxgenjs`, `pdf-lib`, `pdfjs`, `mammoth`), loads on demand.
+`manualChunks` in `vite.config.ts` uses the function form deliberately: the
+object form let Vite's dynamic-import preload helper get hoisted into a vendor
+chunk, which pulled that whole chunk into the initial load.
+
+## Checks
+
+```bash
+npm run check # tsc, strict
+npm run lint # eslint
+npm test # node:test via tsx
+npm run build # tsc + vite build
+```