LiveTemplate is a reactive web framework for Go that uses tree-based DOM diffing to send minimal updates to clients. This document explains the system architecture, design decisions, and operational flow.

New contributor? Start with the Contributor Walkthrough for a hands-on introduction to the 5-phase architecture with code examples and test links.

┌────────────────────────────────────────────────────────────────┐
│                     User Action (Browser)                       │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  Phase 1: PARSE                                                 │
│  Package: internal/parse/                                       │
│  Input:   Template string                                       │
│  Output:  Parsed AST                                            │
│  Job:     Convert Go template syntax to executable form         │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  Phase 2: BUILD                                                 │
│  Package: internal/build/                                       │
│  Input:   Parsed AST + Data                                     │
│  Output:  Tree structure                                        │
│  Job:     Generate tree separating statics from dynamics        │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  Phase 3: DIFF                                                  │
│  Package: internal/diff/                                        │
│  Input:   Old tree + New tree                                   │
│  Output:  Minimal changes                                       │
│  Job:     Calculate what changed                                │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  Phase 4: RENDER                                                │
│  Package: internal/render/                                      │
│  Input:   Tree or Changes                                       │
│  Output:  HTML (for testing and validation)                     │
│  Job:     HTML rendering and minification                       │
└──────────────────────────┬─────────────────────────────────────┘
                           ↓
┌────────────────────────────────────────────────────────────────┐
│  Phase 5: SEND                                                  │
│  Package: internal/send/                                        │
│  Input:   Tree updates + action data                            │
│  Output:  Serialized JSON messages                              │
│  Job:     Message parsing and serialization                     │
└────────────────────────────────────────────────────────────────┘
                           ↓
                    Client applies update

For the complete file-by-file map with line counts and dependencies, see CODE_STRUCTURE.md.

Problem: Sending full HTML on every update wastes bandwidth

Solution: Separate static HTML (structure) from dynamic data (values)

Result:

• First render: Send complete tree with statics ["<div>", "</div>"] + dynamics
• Updates: Send only changed dynamics, client has statics cached
• Bandwidth reduction: 50-90% for typical templates

Example:

// First render
{
  "s": ["<div>Counter: ", "</div>"],
  "0": "5"
}

// Update (client has statics)
{
  "0": "6"
}

Decision: All features work over HTTP, WebSocket only for broadcasts

Rationale:

• ✅ HTTP works everywhere (no proxy/firewall issues)
• ✅ Simpler deployment and debugging
• ✅ Stateless until you need state
• ✅ WebSocket adds complexity, only needed for server-initiated updates

When to use WebSocket:

• Real-time collaboration
• Live notifications
• Server-initiated broadcasts
• Multiple simultaneous updates

Decision: State lives in Go, not split between client/server

Benefits:

• ✅ Type safety via Go's type system
• ✅ No synchronization issues
• ✅ Simpler mental model
• ✅ Backend logic stays in backend
• ✅ No need for API layer

Trade-offs:

• ❌ Not suitable for offline-first apps
• ❌ Requires server round-trip for interactions
• ✅ But: Perfect for admin dashboards, internal tools, forms

Decision: Packages named parse, build, diff, render, send

Benefits:

• ✅ Self-documenting code structure
• ✅ Import list shows execution flow
• ✅ New developers can follow the pipeline
• ✅ Clear separation of concerns
• ✅ Easy to find code (operation → package)

Example:

import (
    "github.com/livetemplate/livetemplate/internal/parse"   // Phase 1
    "github.com/livetemplate/livetemplate/internal/build"   // Phase 2
    "github.com/livetemplate/livetemplate/internal/diff"    // Phase 3
    "github.com/livetemplate/livetemplate/internal/render"  // Phase 4
    "github.com/livetemplate/livetemplate/internal/send"    // Phase 5
)

Large operations are broken into three levels:

1. Orchestrator (25-35 lines)

• Public API entry point
• Calls coordinators in sequence
• Handles errors and logging
• Example: diff.Compute()

2. Coordinators (20-30 lines)

• Handle one aspect of the operation
• Call multiple helpers
• Example: computeUpdates(), computeInserts()

3. Helpers (<15 lines)

• Do ONE thing well
• Pure functions when possible
• Example: extractItemKey(), haveSameKeys()

// Orchestrator (25 lines)
func ComputeRangeDiff(old, new *build.Tree) []RangeOperation {
    oldItems, oldKeys := extractRangeItems(old)
    newItems, newKeys := extractRangeItems(new)

    if isPureReorder(oldItems, newItems, oldKeys, newKeys) {
        return []RangeOperation{createReorderOp(newKeys)}
    }

    ops := []RangeOperation{}
    ops = append(ops, computeUpdates(oldItems, newItems, oldKeys, newKeys)...)
    ops = append(ops, computeInserts(oldItems, newItems, oldKeys, newKeys)...)
    ops = append(ops, computeRemoves(oldItems, newItems, oldKeys, newKeys)...)
    return ops
}

// Coordinator (20-30 lines each)
func computeUpdates(oldItems, newItems []interface{}, oldKeys, newKeys []string) []RangeOperation
func computeInserts(oldItems, newItems []interface{}, oldKeys, newKeys []string) []RangeOperation
func computeRemoves(oldItems, newItems []interface{}, oldKeys, newKeys []string) []RangeOperation

// Helpers (<15 lines each)
func extractRangeItems(tree *build.Tree) ([]interface{}, []string)
func extractItemKey(item interface{}) string
func isPureReorder(oldItems, newItems []interface{}, oldKeys, newKeys []string) bool
func haveSameKeys(keys1, keys2 []string) bool

Benefits:

• Easy to understand (each function fits on screen)
• Easy to test (each function independently testable)
• Easy to modify (change one aspect without affecting others)
• Self-documenting (function names explain intent)

• Frequency: Once per template (cached)
• Complexity: O(n) where n = template size
• Optimization: Parsed templates are reused

• Frequency: Every render
• Complexity: O(n) where n = data size
• Optimization: Structure fingerprinting for O(1) statics decision

• Frequency: Every update (not first render)
• Complexity: O(n) where n = tree node count
• Optimization: Early exit on no changes, range operation detection

• Frequency: Every render/update
• Complexity: O(n) where n = output size
• Optimization: Pre-allocated buffers

Client receives complete tree with statics:

{
  "s": ["<div class='card'>", "<span>", "</span>", "</div>"],
  "0": "Title",
  "1": "Description"
}

Client caches statics for reuse in subsequent updates.

Server uses fingerprint-based comparison to determine if client needs statics:

// Simple 4-case logic (inspired by Phoenix LiveView)
func ClientNeedsStatics(oldTree, newTree *TreeNode) bool {
    if oldTree == nil { return true }   // First render
    if newTree == nil { return false }  // Removal
    return CalculateStructureFingerprint(oldTree) != CalculateStructureFingerprint(newTree)
}

When structure is unchanged, client receives only changed dynamics:

{
  "1": "Updated description"
}

Client uses cached statics + new dynamics to rebuild DOM.

Bandwidth savings: ~90% for typical updates (statics are the largest part)

The fingerprint approach (v0.8.0+) replaces the previous registry-based tracking:

• O(1) comparison instead of path-based registry lookups
• Simpler logic: 4 cases vs 49+ state transitions
• No registry state: Server compares fingerprints directly
• "When in doubt, send full tree": Safe fallback for edge cases

• All dynamic content goes through html/template for automatic escaping
• No direct HTML injection possible
• User content is always escaped

• Configurable Authenticator interface
• Anonymous mode for development
• User-based session isolation for production

• Sessions isolated by user ID
• Session groups for multi-tab support
• Automatic cleanup on disconnect

All logs are structured JSON:

{
  "time": "2025-10-31T12:34:56Z",
  "level": "INFO",
  "msg": "template_executed",
  "template": "todos",
  "data_type": "*main.TodoState",
  "duration_ms": 5,
  "user_id": "user-123",
  "session_id": "sess-456"
}

Emitted periodically via slog:

• Counters: actions_processed, templates_executed, etc.
• Gauges: active_connections, active_groups
• Histograms: p50/p95/p99 latencies

See OBSERVABILITY.md for complete guide.

• Streaming updates for large datasets
• Client-side caching improvements
• Binary diff format (more compact than JSON)
• Diff batching (combine multiple small updates)

• Multi-user broadcast optimization
• Partial tree invalidation
• Template compilation cache
• WebSocket message compression

• OBSERVABILITY.md - Logging and metrics guide
• ROADMAP.md - Project roadmap
• CODE_STRUCTURE.md - Codebase organization
• API Reference - Go package docs