markitect-main/docs/adr/ADR-001-client-side-debug-storage.md

ADR-001: Client-Side Debug Storage Technology

Status

Accepted - 2025-11-10

Context

The Markitect application requires a robust client-side debugging infrastructure to track and display debug messages during document editing operations. The previous implementation relied on a tightly-coupled debug panel that expected specific DOM elements and was integrated into old dialog systems.

Requirements

• Independence: Debug system must be independent of specific UI components
• Persistence: Debug messages should survive browser refresh/close
• Real-time Updates: UI should reflect new messages immediately
• Performance: Should not block the main thread or impact editor performance
• Storage Capacity: Must handle 1000+ debug messages efficiently
• Browser Compatibility: Work across all modern browsers
• Developer Experience: Easy to integrate and use throughout the codebase

Problem Statement

The existing debug infrastructure was failing because:

1. Tight coupling to specific DOM elements (debug-messages-container, toggle-debug)
2. Dependency on old dialog systems
3. No persistence across browser sessions
4. Limited to in-memory storage only

Decision

We will use IndexedDB as the primary client-side storage technology for the debug system.

Alternatives Considered

Option 1: IndexedDB (Selected)

Technology: Browser-native object store database Implementation: window.MarkitectDebugSystem with async operations

Option 2: SQLite via SQL.js

Technology: WebAssembly-based SQLite implementation Implementation: SQL.js library with manual persistence

Option 3: LocalStorage

Technology: Browser key-value storage Implementation: JSON serialization with size limits

Option 4: In-Memory Only

Technology: JavaScript arrays with no persistence Implementation: Simple message array management

Decision Matrix

Criteria	IndexedDB	SQLite	LocalStorage	In-Memory
Storage Capacity	✅ Large (50-100MB+)	✅ Large	❌ Limited (5-10MB)	❌ Session only
Performance	✅ Async/Non-blocking	⚠️ Can block UI	✅ Fast	✅ Fastest
Persistence	✅ Across sessions	✅ Across sessions	✅ Across sessions	❌ Lost on refresh
Query Capabilities	⚠️ Limited	✅ Full SQL	❌ None	❌ JavaScript only
Dependencies	✅ Native	❌ 1.5MB WebAssembly	✅ Native	✅ Native
Browser Support	✅ Universal modern	✅ Universal	✅ Universal	✅ Universal
API Complexity	⚠️ Moderate	✅ Familiar SQL	✅ Simple	✅ Simple
Use Case Fit	✅ Perfect match	⚠️ Overkill	❌ Too limited	❌ Insufficient

Rationale

Why IndexedDB?

1. Native Browser Support: No external dependencies or WebAssembly files
2. Asynchronous Operations: Won't block the UI thread during debug operations
3. Sufficient Storage: 50-100MB+ capacity easily handles thousands of debug messages
4. Appropriate Complexity: Matches our simple data model without over-engineering
5. Performance Optimized: Browsers optimize IndexedDB for web applications
6. Security: Runs within browser's security sandbox with proper origin isolation

Why Not SQLite?

While SQLite offers powerful querying capabilities, it's overkill for our use case:

• Complexity: Our data model is simple (timestamp, category, message)
• Dependencies: 1.5MB WebAssembly adds significant overhead
• Synchronous Risk: Large operations can block the UI thread
• Manual Persistence: Requires explicit save/load operations
• Over-Engineering: We don't need JOINs, complex queries, or relational features

Why Not LocalStorage?

LocalStorage is too limited:

• Size Constraints: 5-10MB limit insufficient for extensive debug logs
• Synchronous API: Blocks main thread during operations
• No Structured Data: JSON serialization/deserialization overhead
• Browser Quotas: Can be evicted under storage pressure

Why Not In-Memory?

In-memory storage is insufficient:

• No Persistence: Debug context lost on page refresh
• Memory Pressure: Large debug logs consume RAM
• Development Workflow: Debugging often requires page reloads

Implementation Details

Data Structure

{
  id: auto_increment_id,
  message: "Debug message text",
  category: "INFO" | "WARNING" | "ERROR" | "SUCCESS" | "DEBUG",
  timestamp: "2025-11-10T23:35:53.123Z",
  displayTime: "11:35:53 PM"
}

Database Schema

• Store Name: messages
• Key Path: id (auto-increment)
• Indexes: timestamp, category
• Version: 1

API Design

// Core operations
await MarkitectDebugSystem.addMessage(message, category);
await MarkitectDebugSystem.clearMessages();
const messages = MarkitectDebugSystem.getMessages(category, limit);

// Advanced features
const unsubscribe = MarkitectDebugSystem.subscribe(callback);
const json = MarkitectDebugSystem.exportMessages();

Consequences

Positive

• ✅ Zero Dependencies: No external libraries required
• ✅ High Performance: Non-blocking operations maintain UI responsiveness
• ✅ Persistent Debugging: Debug context preserved across browser sessions
• ✅ Scalable Storage: Handles thousands of debug messages efficiently
• ✅ Future-Proof: Can add advanced features without architectural changes
• ✅ Developer-Friendly: Simple API integration throughout codebase

Negative

• ⚠️ Limited Querying: Complex filtering requires custom JavaScript code
• ⚠️ Browser Variations: Subtle differences in IndexedDB implementations
• ⚠️ Learning Curve: Developers may be less familiar with IndexedDB vs SQL

Mitigation Strategies

• Query Limitations: Implement helper methods for common filtering operations
• Browser Compatibility: Use feature detection with graceful fallbacks
• Developer Experience: Provide clear API documentation and examples

Future Considerations

Potential Enhancements

1. Hybrid Approach: Add optional SQLite mode for advanced users
2. Data Export: Multiple export formats (JSON, CSV, SQL dumps)
3. Advanced Filtering: Web Workers for complex query operations
4. Data Visualization: Charts and analytics for debug patterns
5. Remote Sync: Optional sync to development servers

Migration Path

The current IndexedDB implementation provides a foundation that could support:

• Adding SQLite as an "advanced mode" option
• Implementing data export to external analysis tools
• Building analytics dashboards on top of the debug data

References

• IndexedDB API Documentation
• SQL.js Documentation
• Web Storage API Limitations

Approval

Decided by: Claude Code Development Team Date: 2025-11-10 Context: Independent debug system redesign Next Review: When complex querying requirements emerge