diff --git a/SERVER_UPDATE.md b/SERVER_UPDATE.md new file mode 100644 index 0000000..650666d --- /dev/null +++ b/SERVER_UPDATE.md @@ -0,0 +1,232 @@ +# Server Update Plan - Phase 3a: HTML-First API Architecture + +## 🎯 Current Status & Vision + +### **What We Discovered** +Our frontend has evolved to a sophisticated **HTML-first approach** with: +- Style-aware editing with automatic style detection +- HTML preservation with perfect attribute fidelity +- Rich content editing capabilities +- Template-based style preservation + +However, our **server API is still text-focused**, creating a fundamental mismatch between frontend capabilities and backend storage. + +### **Core Issues Identified** +1. **Storage Mismatch**: Server stores plain text (`value`), frontend produces rich HTML +2. **Style Loss**: Developer-defined styles disappear when unused by editors +3. **Template Preservation**: Need to maintain original developer markup for style detection +4. **Dual Mode Challenge**: Development iteration vs. production stability requirements + +## 🏗️ Proposed Architecture Changes + +### **1. HTML-First Database Schema** + +**Updated Schema (No Backwards Compatibility Required):** +```sql +CREATE TABLE content ( + id TEXT PRIMARY KEY, + site_id TEXT NOT NULL, + html_content TEXT NOT NULL, -- Rich HTML (for BOTH editing AND injection) + original_markup TEXT, -- Developer template markup (for style detection) + template_locked BOOLEAN DEFAULT FALSE, -- Development vs Production mode + type TEXT NOT NULL, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL, + last_edited_by TEXT NOT NULL, + UNIQUE(site_id, id) +); + +CREATE TABLE content_versions ( + version_id INTEGER PRIMARY KEY AUTOINCREMENT, + content_id TEXT NOT NULL, + site_id TEXT NOT NULL, + html_content TEXT NOT NULL, -- Version HTML content + original_markup TEXT, -- Template at time of version + type TEXT NOT NULL, + created_at INTEGER NOT NULL, + created_by TEXT NOT NULL +); +``` + +**Key Changes:** +- ✅ **Removed `value` field** - HTML serves both editing and injection needs +- ✅ **Added `original_markup`** - Preserves developer templates for style detection +- ✅ **Added `template_locked`** - Controls template update behavior +- ✅ **Unified storage** - Same HTML content used for build injection and editing + +### **2. Template Lifecycle Management** + +#### **Development Mode (template_locked = false):** +- Enhancement **updates templates** when developer markup changes significantly +- API editing **preserves templates**, only updates content +- Supports rapid iteration and template refinement + +#### **Production Mode (template_locked = true):** +- Enhancement **preserves existing templates** regardless of markup changes +- API editing **never affects templates** +- Ensures developer styles always available to clients + +#### **Template Management Commands:** +```bash +# Lock templates for production handoff +insertr templates lock --site-id mysite + +# Edit specific template (opens in $EDITOR) +insertr templates edit --site-id mysite --content-id hero-title-abc123 + +# Show template status +insertr templates status --site-id mysite +``` + +### **3. Updated Content Processing Flow** + +#### **Enhancement Process:** +```go +func (e *ContentEngine) processElement(node *html.Node, siteID, contentID string, devMode bool) { + existingContent := getContent(siteID, contentID) + currentMarkup := extractElementHTML(node) + + if existingContent == nil { + // First time: create with template + htmlContent := extractContentHTML(node) + createContent(siteID, contentID, htmlContent, currentMarkup, !devMode) + } else if devMode && !existingContent.TemplateLocked { + // Dev mode: update template if changed, preserve content + if hasSignificantStyleChanges(existingContent.OriginalMarkup, currentMarkup) { + updateTemplate(siteID, contentID, currentMarkup) + } + } + // Always inject existing html_content + injectHTMLContent(node, existingContent.HTMLContent) +} +``` + +#### **API Content Updates:** +```go +func (h *ContentHandler) CreateContent(req CreateContentRequest) { + // API updates only affect html_content, never original_markup + updateContent(req.SiteID, req.ID, req.HTMLContent) + // Template preservation handled automatically +} +``` + +### **4. Frontend Integration** + +#### **Style Detection Using Templates:** +```javascript +// Always use stored template for style detection +async initializeEditor(element) { + const response = await this.apiClient.getContent(element.dataset.contentId); + + // Use original_markup for consistent style detection + const templateHTML = response.original_markup || element.outerHTML; + this.styleEngine.detectStylesFromHTML(templateHTML); + + // Use html_content for editor initialization + this.editor.setContent(response.html_content); +} +``` + +#### **Updated API Response:** +```json +{ + "id": "hero-title-abc123", + "html_content": "