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": "

Welcome to Our Company

", + "original_markup": "

Welcome to Our Company

", + "template_locked": true, + "type": "text" +} +``` + +## 🔄 Development Workflows + +### **Development Phase:** +```bash +# Start development (templates auto-update) +insertr serve --dev-mode + +# Developer changes files -> enhancement updates templates automatically +# Editor changes content -> templates preserved, only content updated +# Style detection uses current templates (reflecting latest dev intent) + +# Ready for handoff: +insertr templates lock --site-id mysite +``` + +### **Production Phase:** +```bash +# Production mode (templates locked by default) +insertr serve + +# Client editing -> only html_content changes, templates preserved +# Style detection always uses locked original_markup +# Developer styles always available regardless of content changes + +# For style updates: +insertr templates edit --site-id mysite --content-id specific-element +``` + +## 🎯 Key Benefits + +### **For Developers:** +✅ **Rapid iteration** during development with automatic template updates +✅ **Explicit control** over template locking and updates +✅ **HTML-first approach** aligns with frontend capabilities +✅ **Clean schema** without legacy compatibility concerns + +### **For Clients:** +✅ **Style preservation** - developer styles always available +✅ **Rich editing** with full HTML capabilities +✅ **Version history** includes both content and template context +✅ **Design safety** - cannot accidentally break developer styling + +### **For System:** +✅ **Unified processing** - same HTML used for injection and editing +✅ **Clear separation** between content updates and template management +✅ **Dev/prod integration** leverages existing mode detection +✅ **Self-contained** templates preserved in database + +## 📋 Implementation Tasks + +### **Phase 3a Priority Tasks:** + +1. **Database Schema Update** + - [ ] Update `content` table schema + - [ ] Update `content_versions` table schema + - [ ] Update SQLC queries and models + +2. **API Model Updates** + - [ ] Update `ContentItem` and `CreateContentRequest` structs + - [ ] Add `html_content` and `original_markup` fields + - [ ] Remove `value` field dependencies + +3. **Enhancement Process Updates** + - [ ] Update content injection to use `html_content` instead of `value` + - [ ] Add template detection and storage logic + - [ ] Implement dev/prod mode template handling + +4. **Template Management Commands** + - [ ] Add `insertr templates` command group + - [ ] Implement `lock`, `edit`, `status` subcommands + - [ ] Add template validation and editor integration + +5. **Frontend Integration** + - [ ] Update API client to handle new response format + - [ ] Modify style detection to use `original_markup` + - [ ] Test rich HTML content editing and injection + +## 🔍 Next Steps + +Tomorrow we will: +1. **Begin database schema implementation** +2. **Update SQLC queries and regenerate models** +3. **Modify API handlers for new content structure** +4. **Test the template lifecycle management** + +This represents a fundamental shift to **HTML-first content management** while maintaining the zero-configuration philosophy that makes Insertr unique. + +--- + +**Status**: Planning Complete, Ready for Implementation +**Estimated Effort**: 1-2 days for core implementation +**Breaking Changes**: Yes (fresh schema, no migration needed) \ No newline at end of file