Azornes-Comfyui-LayerForge/Doc/ARCHITECTURE.md

LayerForge frontend architecture

The TypeScript files under src/ are the frontend source of truth. The tracked JavaScript files under js/ are generated by build.bat and must not be edited independently.

Domain responsibilities

Domain	Responsibility
app/	ComfyUI extension registration, node lifecycle, and application composition
canvas/	Canvas state, layers, rendering, interaction, tools, and layer panel
io/	Input connections, tensor/image transport, and canvas output transport
mask/	Mask editing, pixel processing, SAM, and matting integrations
media/	Image/blob conversion, in-memory image cache, preview, upload, and export helpers
persistence/	IndexedDB state, reference tracking, and state worker
shared/	Cross-domain types and errors
utils/	Small cross-cutting 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/canvas_view.ts composes the canvas runtime without registering a second ComfyUI extension as an import side effect.
• app/layer_forge_connections.ts owns graph identity, workflow connections, and ComfyUI event/WebSocket integration.
• canvas/canvas_history.ts owns bounded undo/redo stacks and snapshot cloning.
• io/canvas_io.ts owns image input/output transport and render/export coordination.
• media/image_cache.ts owns in-memory image identity and cache lifetime; IndexedDB persistence remains under persistence/.
• mask/mask_result_utils.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. The lower-level domains remain independent of application composition:

• shared/ must not import frontend domains at runtime;
• media/ must not import app/, canvas/, io/, mask/, or persistence/;
• persistence/ must not import app/, io/, mask/, or media/;
• type-only imports may describe relationships without creating runtime dependencies;
• ComfyUI-provided modules under scripts/ are external runtime dependencies.

The root src/canvas_view.ts file is the single served bootstrap. It invokes the registration function from src/app/canvas_view.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/.