# 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": "<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:**
```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)