insertr/SERVER_UPDATE.md

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

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:

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

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:

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:

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

{
    "id": "hero-title-abc123",
    "html_content": "<h1>Welcome to <em>Our</em> Company</h1>",
    "original_markup": "<h1 class=\"insertr\">Welcome to <span class=\"brand\">Our Company</span></h1>",
    "template_locked": true,
    "type": "text"
}

🔄 Development Workflows

Development Phase:

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

# 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)