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: write down the shape a workspace takes, and align the three

codingFeng10141121b16dd47
diff --git a/client/workspaces/flow/chat/ChatInput.tsx b/client/workspaces/flow/chat/ChatInput.tsx
index 5a8a363..05f8ffa 100644
--- a/client/workspaces/flow/chat/ChatInput.tsx
+++ b/client/workspaces/flow/chat/ChatInput.tsx
@@ -16,7 +16,7 @@ import { toast } from "sonner"
import { ButtonWithTooltip } from "@/shared/chat"
import { ErrorToast } from "@/workspaces/flow/chat/error-toast"
import { GlobalConstraintsDialog } from "@/shared/chat"
-import { STORAGE_KEYS } from "@/workspaces/flow/lib/storage";
+import { STORAGE_KEYS } from "@/workspaces/flow/storage";
import { HistoryDialog } from "@/workspaces/flow/chat/history-dialog"
import { ResetWarningModal } from "@/shared/chat"
import { Textarea } from "@/shared/ui/textarea"
diff --git a/client/workspaces/flow/chat/ChatPanel.tsx b/client/workspaces/flow/chat/ChatPanel.tsx
index 0cabc84..0357672 100644
--- a/client/workspaces/flow/chat/ChatPanel.tsx
+++ b/client/workspaces/flow/chat/ChatPanel.tsx
@@ -12,7 +12,7 @@ import { Toaster, toast } from "sonner"
import { ButtonWithTooltip } from "@/shared/chat"
import { ChatInput } from "@/workspaces/flow/chat/ChatInput"
import { SettingsDialog } from "@/workspaces/flow/chat/settings-dialog"
-import { STORAGE_KEYS } from "@/workspaces/flow/lib/storage";
+import { STORAGE_KEYS } from "@/workspaces/flow/storage";
import { useDiagram } from "@/workspaces/flow/state/diagram-context"
import { useFlowT } from "@/workspaces/flow/lib/translations"
import { getAIConfig } from "@/workspaces/flow/lib/ai-config"
@@ -25,7 +25,7 @@ import {
isTextFile,
} from "@/shared/files"
import { type FileData, useFileProcessor } from "@/shared/files/use-file-processor"
-import { useQuotaManager } from "@/workspaces/flow/lib/use-quota-manager"
+import { useQuotaManager } from "@/workspaces/flow/hooks/use-quota-manager"
import { applyDiagramOperations, isMxCellXmlComplete, type DiagramOperation } from "@/workspaces/flow/lib/diagram-operations"
import { formatXML, validateAndFixXml, wrapWithMxFile } from "@/workspaces/flow/lib/drawio-xml"
import { ChatMessageDisplay } from "./ChatMessageDisplay"
diff --git a/client/workspaces/flow/lib/use-quota-manager.tsx b/client/workspaces/flow/hooks/use-quota-manager.tsx
similarity index 99%
rename from client/workspaces/flow/lib/use-quota-manager.tsx
rename to client/workspaces/flow/hooks/use-quota-manager.tsx
index 064790f..57f571b 100644
--- a/client/workspaces/flow/lib/use-quota-manager.tsx
+++ b/client/workspaces/flow/hooks/use-quota-manager.tsx
@@ -3,7 +3,7 @@
import { useCallback, useMemo } from "react"
import { toast } from "sonner"
import { QuotaLimitToast } from "@/workspaces/flow/chat/quota-limit-toast"
-import { STORAGE_KEYS } from "@/workspaces/flow/lib/storage"
+import { STORAGE_KEYS } from "@/workspaces/flow/storage"
export interface QuotaConfig {
dailyRequestLimit: number
diff --git a/client/workspaces/flow/lib/ai-config.ts b/client/workspaces/flow/lib/ai-config.ts
index 620b8b8..d6d79f5 100644
--- a/client/workspaces/flow/lib/ai-config.ts
+++ b/client/workspaces/flow/lib/ai-config.ts
@@ -1,4 +1,4 @@
-import { STORAGE_KEYS } from "@/workspaces/flow/lib/storage"
+import { STORAGE_KEYS } from "@/workspaces/flow/storage"
import { DEFAULT_AI_CONFIG } from "@contracts/ai";
import { getAIConfig as getWorkspaceAIConfig } from "@/ai/storage";
import type { AIConfig } from "@contracts/ai"
diff --git a/client/workspaces/flow/lib/storage.ts b/client/workspaces/flow/storage.ts
similarity index 100%
rename from client/workspaces/flow/lib/storage.ts
rename to client/workspaces/flow/storage.ts
diff --git a/client/workspaces/ppt/canvas/PptCanvas.tsx b/client/workspaces/ppt/canvas/PptCanvas.tsx
index 22a39bf..54d6ee6 100644
--- a/client/workspaces/ppt/canvas/PptCanvas.tsx
+++ b/client/workspaces/ppt/canvas/PptCanvas.tsx
@@ -53,7 +53,7 @@ import {
EDITABLE_EXPORT_CONCURRENCY,
EDITABLE_REVIEW_CONCURRENCY,
MODEL_CONCURRENCY,
-} from "@/workspaces/ppt/canvas/constants";
+} from "@/workspaces/ppt/canvas/lib/constants";
import {
deriveTextElementsFromBlocks,
hasRenderableTextBlocks,
@@ -62,7 +62,7 @@ import {
normalizeLocalizedSlideTitle,
parseSlideNo,
stripLeadingBullet,
-} from "@/workspaces/ppt/canvas/slide-content";
+} from "@/workspaces/ppt/canvas/lib/slide-content";
import {
filterRecordByAllowedKeys,
migrateLegacyTextlessVersions,
@@ -74,7 +74,7 @@ import {
normalizePersistedStringMap,
persistImageUrlIfNeeded,
shouldInlinePersistImageUrl,
-} from "@/workspaces/ppt/canvas/persisted-state";
+} from "@/workspaces/ppt/canvas/lib/persisted-state";
import type {
PptData,
ReferenceVisualAsset,
diff --git a/client/workspaces/ppt/canvas/hooks/use-template-library.ts b/client/workspaces/ppt/canvas/hooks/use-template-library.ts
index 70629dc..3da7ae4 100644
--- a/client/workspaces/ppt/canvas/hooks/use-template-library.ts
+++ b/client/workspaces/ppt/canvas/hooks/use-template-library.ts
@@ -6,14 +6,14 @@ import {
PPT_TEMPLATE_HIDDEN_PRESETS_KEY,
PPT_TEMPLATE_UPLOADS_KEY,
PRESET_TEMPLATES,
-} from "@/workspaces/ppt/canvas/constants";
+} from "@/workspaces/ppt/canvas/lib/constants";
import {
normalizePersistedStringArray,
normalizePersistedUploadedTemplates,
persistImageUrlIfNeeded,
readLegacyHiddenPresetTemplateIds,
readLegacyUploadedTemplates,
-} from "@/workspaces/ppt/canvas/persisted-state";
+} from "@/workspaces/ppt/canvas/lib/persisted-state";
import type { TemplateItem, UploadTemplate } from "@/workspaces/ppt/canvas/types";
type Translate = (zh: string, en: string) => string;
diff --git a/client/workspaces/ppt/canvas/constants.ts b/client/workspaces/ppt/canvas/lib/constants.ts
similarity index 100%
rename from client/workspaces/ppt/canvas/constants.ts
rename to client/workspaces/ppt/canvas/lib/constants.ts
diff --git a/client/workspaces/ppt/canvas/persisted-state.ts b/client/workspaces/ppt/canvas/lib/persisted-state.ts
similarity index 98%
rename from client/workspaces/ppt/canvas/persisted-state.ts
rename to client/workspaces/ppt/canvas/lib/persisted-state.ts
index b1aced2..5163f38 100644
--- a/client/workspaces/ppt/canvas/persisted-state.ts
+++ b/client/workspaces/ppt/canvas/lib/persisted-state.ts
@@ -1,5 +1,5 @@
-import { PPT_TEMPLATE_HIDDEN_PRESETS_KEY, PPT_TEMPLATE_UPLOADS_KEY } from "@/workspaces/ppt/canvas/constants";
-import { deriveTextElementsFromBlocks, hasRenderableTextBlocks } from "@/workspaces/ppt/canvas/slide-content";
+import { PPT_TEMPLATE_HIDDEN_PRESETS_KEY, PPT_TEMPLATE_UPLOADS_KEY } from "@/workspaces/ppt/canvas/lib/constants";
+import { deriveTextElementsFromBlocks, hasRenderableTextBlocks } from "@/workspaces/ppt/canvas/lib/slide-content";
import type {
SlideData,
SlideImageVersion,
diff --git a/client/workspaces/ppt/canvas/lib/render-layers.ts b/client/workspaces/ppt/canvas/lib/render-layers.ts
index 6c8760f..b0ab8f7 100644
--- a/client/workspaces/ppt/canvas/lib/render-layers.ts
+++ b/client/workspaces/ppt/canvas/lib/render-layers.ts
@@ -1,4 +1,4 @@
-import { mergeTextBlocksIntoElements } from "@/workspaces/ppt/canvas/slide-content";
+import { mergeTextBlocksIntoElements } from "@/workspaces/ppt/canvas/lib/slide-content";
import type { SlideRenderLayer } from "@/workspaces/ppt/canvas/types";
import type { PptTextBlock } from "@/workspaces/ppt/lib/ppt-service";
diff --git a/client/workspaces/ppt/canvas/slide-content.ts b/client/workspaces/ppt/canvas/lib/slide-content.ts
similarity index 100%
rename from client/workspaces/ppt/canvas/slide-content.ts
rename to client/workspaces/ppt/canvas/lib/slide-content.ts
diff --git a/client/workspaces/ppt/canvas/lib/slide-versions.ts b/client/workspaces/ppt/canvas/lib/slide-versions.ts
index b4efbea..4303581 100644
--- a/client/workspaces/ppt/canvas/lib/slide-versions.ts
+++ b/client/workspaces/ppt/canvas/lib/slide-versions.ts
@@ -1,4 +1,4 @@
-import { SYNTHETIC_PRIMARY_VERSION_PREFIX } from "@/workspaces/ppt/canvas/constants";
+import { SYNTHETIC_PRIMARY_VERSION_PREFIX } from "@/workspaces/ppt/canvas/lib/constants";
import type { SlideImageVersion } from "@/workspaces/ppt/canvas/types";
/**
diff --git a/client/workspaces/ppt/canvas/views/DeckView.tsx b/client/workspaces/ppt/canvas/views/DeckView.tsx
index bbc6cfe..3aecf37 100644
--- a/client/workspaces/ppt/canvas/views/DeckView.tsx
+++ b/client/workspaces/ppt/canvas/views/DeckView.tsx
@@ -36,7 +36,7 @@ import {
PPT_REFERENCE_SLIDE_HEIGHT,
PPT_REFERENCE_SLIDE_WIDTH,
} from "@/workspaces/ppt/lib/ppt-service";
-import { hasRenderableTextBlocks } from "@/workspaces/ppt/canvas/slide-content";
+import { hasRenderableTextBlocks } from "@/workspaces/ppt/canvas/lib/slide-content";
import { getSlideshowDimensions } from "@/workspaces/ppt/canvas/lib/slideshow-size";
import { reviewProgressSummary, type ReviewProgress } from "@/workspaces/ppt/canvas/lib/review-progress";
import { ReviewSelectionOverlay } from "@/workspaces/ppt/canvas/views/ReviewSelectionOverlay";
diff --git a/client/workspaces/ppt/canvas/views/ReviewSelectionOverlay.tsx b/client/workspaces/ppt/canvas/views/ReviewSelectionOverlay.tsx
index 4679e88..3ac9405 100644
--- a/client/workspaces/ppt/canvas/views/ReviewSelectionOverlay.tsx
+++ b/client/workspaces/ppt/canvas/views/ReviewSelectionOverlay.tsx
@@ -1,7 +1,7 @@
import {
REVIEW_BOX_COLOR,
REVIEW_BOX_SELECTED_COLOR,
-} from "@/workspaces/ppt/canvas/constants";
+} from "@/workspaces/ppt/canvas/lib/constants";
import type {
ReviewResizeHandle,
SlideData,
diff --git a/docs/architecture.md b/docs/architecture.md
index e2d9b28..0bdd1f4 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -14,7 +14,8 @@ client/ the browser app
<Id>Workspace.tsx the entry the registry lazy-loads
canvas/ the canvas half
chat/ the chat half
- lib/ logic only that workspace uses
+ lib/ pure logic only that workspace uses
+ hooks/ its stateful pieces
storage.ts its persisted keys
features/ppt-editor/ the editable-slide bridge
pages/portal/ the landing page
@@ -57,14 +58,60 @@ paths.
**Storage keys are load-bearing.** IndexedDB database names and localStorage
keys carry users' saved work across releases. Each workspace names its own in
-`workspaces/<id>/storage.ts`; Flow's are in `workspaces/flow/lib/storage.ts`
-and keep their original `next-ai-draw-io-` prefix from before that workspace
-was folded in. Renaming one orphans whatever was stored under it.
+`workspaces/<id>/storage.ts`. Flow's keep their original
+`next-ai-draw-io-` prefix from before that workspace was folded in. Renaming
+one orphans whatever was stored under it.
**`resources/` is data, not documentation or source.** The server reads it with
`readFile` at request time, so a deployment has to ship it — see the Dockerfile.
`server/chat/resources.ts` is the only place those paths are written down.
+## Inside a workspace
+
+A canvas grows in one direction: the component that owns the screen keeps
+getting bigger. `PptCanvas.tsx` reached 5,300 lines that way. The shape below
+is what it was split into, and what to reach for when another one gets there.
+
+Three layers, by how much of React they need:
+
+**`lib/` — none.** Plain functions over plain values. The version a slide
+resolves to, the geometry of a resize handle, the shape of a prompt, whether a
+reply carries a patch. These are where the rules live, so these are what the
+tests cover; everything under `tests/` is one of these.
+
+**`hooks/` — state and effects, one feature each.** `useTemplateLibrary` owns
+the template picker and nothing else. A hook that needs something another
+feature owns takes it as an argument rather than reaching for it:
+`useExportReview` is handed the text-block editors because the render layer
+belongs to the canvas, not to review.
+
+**`views/` — JSX only.** One file per screen, taking the hooks' return values
+as props. A view holding its own state means the state was in the wrong place.
+
+### Order matters
+
+Extract the state before the view, and count the props first to know which
+you are doing. The PPT start screen needed thirty separate values from the
+component; after `useCreationInputs` it needed nine, four of them handlers.
+The outline review went from seventeen to eight the same way. Pulling either
+out first would have traded a long file for a long prop list.
+
+### Not everything belongs in a hook
+
+The deck itself — `localSlides` and its companions — stayed in `PptCanvas`.
+Every generation flow touches it, 214 references, and prefixing all of them to
+reach through a hook would make the flows harder to read, not easier. The five
+clusters that did come out were each touched by one feature.
+
+The test is whether a boundary already exists. If it does, a hook names it. If
+it does not, a hook invents one and everything downstream pays for it.
+
+### Naming
+
+PascalCase for a screen or a panel — `DeckView.tsx`, `ChatPanel.tsx`.
+kebab-case for a piece — a leaf component, a hook, a module. `shared/` is
+kebab throughout.
+
## The model client
Every model call speaks the OpenAI HTTP protocol:
diff --git a/tests/ppt-persisted-state.test.ts b/tests/ppt-persisted-state.test.ts
index 490a406..8a09781 100644
--- a/tests/ppt-persisted-state.test.ts
+++ b/tests/ppt-persisted-state.test.ts
@@ -12,7 +12,7 @@ import {
normalizePersistedStringMap,
normalizePersistedUploadedTemplates,
shouldInlinePersistImageUrl,
-} from "../client/workspaces/ppt/canvas/persisted-state";
+} from "../client/workspaces/ppt/canvas/lib/persisted-state";
/**
* These readers stand between a user's saved deck and the workspace. Every one
diff --git a/tests/ppt-slide-versions.test.ts b/tests/ppt-slide-versions.test.ts
index 148fe6b..ae10dc0 100644
--- a/tests/ppt-slide-versions.test.ts
+++ b/tests/ppt-slide-versions.test.ts
@@ -7,7 +7,7 @@ import {
resolveSlideVersion,
type VersionState,
} from "../client/workspaces/ppt/canvas/lib/slide-versions";
-import { SYNTHETIC_PRIMARY_VERSION_PREFIX } from "../client/workspaces/ppt/canvas/constants";
+import { SYNTHETIC_PRIMARY_VERSION_PREFIX } from "../client/workspaces/ppt/canvas/lib/constants";
import type { SlideImageVersion } from "../client/workspaces/ppt/canvas/types";
/**