Add Phase 3a server update planning document
- Document HTML-first API architecture vision - Define template lifecycle management system - Plan schema updates for content and template storage - Outline development vs production mode handling - Specify implementation tasks and priorities
This commit is contained in:
232
SERVER_UPDATE.md
Normal file
232
SERVER_UPDATE.md
Normal file
@@ -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": "<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)
|
||||
Reference in New Issue
Block a user