This document details the technical architecture of the SveltyCMS Collection Builder. It explains how the system maintains a “Single Source of Truth” by reconciling filesystem definitions with database state and presenting a consistent view to the user.

System Overview

The Collection Builder operates on a Canonical Flat List architecture. Instead of storing complex nested trees, both the server and the UI operate on flat arrays of nodes that are linked via parentId.

Core Data Flow

The following diagram illustrates the reconciliation flow:

Key Components

1. Filesystem (The Configuration Truth)

The config/collections directory is the primary source of truth for Collections (existence and structure).

• If a collection file exists on disk, it MUST exist in the system.
• If a file is deleted from disk, the corresponding collection is marked for deletion (or becomes a “ghost” if not cleaned up).

2. ContentSystem (The Reconciliation Engine)

Located at src/content/index.ts, this singleton is responsible for bridging the gap between static files and dynamic database state.

Key responsibilities:

• Startup Sync: On boot, it scans compiledCollections and compares them against the system_content_structure table/collection in the active database adapter.
• Defensive Import: It actively filters out “garbage” nodes from the database (e.g., nodes where path is a UUID instead of a valid file path) to prevent database corruption from looping back into the application state.
• ID Persistence: While collection definitions come from disk, _id, parentId, and order are preserved from the database and manifest (collectionOrder, structureNodes).
• Save without destructive refresh: executeGuiStructureSave() (via saveContentStructure remote or legacy ?/saveConfig action) upserts move / rename / create / delete operations through syncContentState({ reason: "gui-save" }), syncs contentStore, writes the manifest, and broadcasts SSE — it does not call fullReload().
• Schema save: Editor saveCollection writes .ts then syncContentState({ reason: "collection-save", targetFile }) — compile + incremental refresh + model provision under a GUI compile lock so the Vite watcher does not double-compile.
• Soft UI refresh: Presets, quick-start, and structure saves use invalidate("app:content") only — no window.location.reload() (session, consent, and builder context stay intact).
• Boot manifest watchdog: On syncContentState({ reason: "boot" }), reconcileOrganizationalManifest() compares .compilation-manifest.json (collectionOrder, structureNodes) against the DB flat structure and re-aligns the manifest when drift is detected (e.g. after manual DB edits).
• Cross-tab sync: Server-side saves call notifyContentUpdate(); the browser contentSystem.refresh() handler syncs both contentStore and collectionStore.contentStructure so the sidebar updates without navigation.

3. Organizational vs Filesystem Boundaries

4. Integrity & Safety Layer

Located in src/utils/schema/ and src/services/MigrationEngine.ts, this layer guards against data corruption:

• Tree Validator: Prevents cyclic dependencies (A->B->A) and path collisions during reordering.
• Drift Detection: Compares the Code Definition (Target) vs Database Schema (Current) to detect potentially destructive changes (e.g., removing a field, changing a widget type).
• Migration Engine: Orchestrates necessary DB updates agnostically via the IDBAdapter interface, ensuring compatibility across different database backends.

5. Database (State & Metadata)

The active database adapter stores the metadata that cannot live in static files, specifically:

• _id: The stable UUID for the collection.
• parentId: Which category or folder the collection currently resides in.
• order: The sort order within that parent.

6. Client UI (The View)

The Collection Builder board (tree-view-board.svelte) and admin sidebar (collections.svelte → tree-view.svelte) both consume the same contentStructure store. The sidebar additionally applies page.data.collectionOrder from the manifest for user-defined sort overrides.

• Input: A flat array of ContentNode objects from the API.
• Process: A lightweight buildTree function groups nodes by parentId.
• Render: The UI renders the hierarchical tree based on this computed logical structure.
• Interaction: Drag-and-drop operations do not mutate the tree structure directly. Instead, they emit updates to the flat list (e.g., updateNode(id, { parentId: newParent })), which triggers a server save and a reactive re-render.

⌨️ Keyboard-Driven UX

The Collection Builder is designed for rapid iteration using a unified hotkey system.

Standard Controls

• Mod + S: Save the entire collection and trigger database reconciliation.
• Escape: Cancel current operation or exit the builder shell.

BuzzForm (Visual Canvas)

• Delete: Instantly remove the selected field from the canvas.
• Mod + D: Duplicate the selected field, automatically generating a unique db_fieldName.

Widget Editor (Multi-Step)

• Mod + Enter: Advance to the next configuration step or “Finish” the widget.
• Escape: Navigate back to the previous step.

Failure Scenarios & Recovery

Related Architecture

• Compilation Pipeline — ContentSync, atomic compile, HMR payload
• Content System Architecture — coordinator, stores, SSE
• Collection Store Data Flow — active collection SSR flow

Tests