From 080bd8fb6043e29ccb2c5135e9ae8a4671de2f5a Mon Sep 17 00:00:00 2001
From: Dariusz L <dl122@wp.pl>
Date: Fri, 14 Aug 2026 12:10:22 +0200
Subject: [PATCH] docs: document frontend architecture

---
 Doc/ARCHITECTURE.md | 29 +++++++++++++++++++++++++++++
 Doc/BUILDING.md     | 10 ++++++++++
 2 files changed, 39 insertions(+)

diff --git a/Doc/ARCHITECTURE.md b/Doc/ARCHITECTURE.md
index b6f3ecf..bca91b2 100644
--- a/Doc/ARCHITECTURE.md
+++ b/Doc/ARCHITECTURE.md
@@ -18,6 +18,30 @@ be edited independently.
 | `utils/` | Small compatibility and UI helpers that have not yet earned a domain |
 | `log_system/` | Canonical logging implementation |
 
+## Canonical modules
+
+These modules are the main seams between the frontend domains:
+
+- `app/CanvasView.ts` composes the canvas runtime without registering a second
+  ComfyUI extension as an import side effect.
+- `app/LayerForgeConnections.ts` owns graph identity, workflow connections,
+  and ComfyUI event/WebSocket integration.
+- `canvas/CanvasHistory.ts` owns bounded undo/redo stacks and snapshot
+  cloning.
+- `io/CanvasIO.ts` owns image input/output transport and render/export
+  coordination.
+- `media/ImageCache.ts` owns in-memory image identity and cache lifetime;
+  IndexedDB persistence remains under `persistence/`.
+- `mask/MaskResultUtils.ts` owns shared mask-result conversion and application;
+  editor-specific side effects stay in the individual integrations.
+- `persistence/contracts.ts` owns the shared persisted-state and worker-message
+  contracts used by the database and persistence worker.
+
+New code should use these seams instead of reaching into another domain's
+implementation details. If a dependency cannot follow the direction below,
+introduce a narrow contract or move the shared behavior to the lowest domain
+that owns it.
+
 ## Dependency direction
 
 `app/` is the composition layer and may depend on the other frontend domains.
@@ -35,3 +59,8 @@ the registration function from `src/app/CanvasView.ts`; the implementation
 module itself must not register the extension as an import side effect.
 
 The dependency rules are covered by `tests/test_architecture_boundaries.mjs`.
+
+Frontend contract and characterization tests live in `tests/*.mjs`. Run
+`npm test`, `npm run lint`, and `npx tsc --noEmit` after frontend changes; run
+`build.bat` first when TypeScript, CSS, or template sources changed so the
+tracked `js/` output stays synchronized with `src/`.
diff --git a/Doc/BUILDING.md b/Doc/BUILDING.md
index 82fabc9..4add015 100644
--- a/Doc/BUILDING.md
+++ b/Doc/BUILDING.md
@@ -36,11 +36,21 @@ The generated files in `js/` are served by ComfyUI. Keep `src/` as the source of
 The frontend is organized by responsibility:
 
 - `src/CanvasView.ts` is the stable ComfyUI bootstrap. Its implementation is in `src/app/CanvasView.ts`.
+- `src/app/LayerForgeConnections.ts` contains graph identity, workflow
+  connections, and ComfyUI event/WebSocket integration used by the canvas.
 - `src/canvas/` contains the canvas facade, layers, state, rendering, selection, tools, and interactions.
+- `src/canvas/CanvasHistory.ts` contains the bounded undo/redo snapshot model.
 - `src/io/` contains ComfyUI input and output handling.
 - `src/mask/` contains mask editing, mask algorithms, and detector/editor integrations.
+- `src/mask/MaskResultUtils.ts` contains shared mask-result conversion and
+  application helpers; SAM and matting integrations retain their own side
+  effects.
 - `src/media/` contains image, blob, upload, preview, and export helpers.
+- `src/media/ImageCache.ts` contains the in-memory image cache. IndexedDB image
+  persistence and reference tracking remain in `src/persistence/`.
 - `src/persistence/` contains IndexedDB and image-reference persistence.
+- `src/persistence/contracts.ts` contains shared persisted-state and worker
+  message contracts.
 - `src/shared/` contains shared types, configuration, error handling, and compatibility exports.
 - `src/utils/` contains smaller cross-cutting browser and ComfyUI helpers.