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
```javascript
{
  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
```javascript
// 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](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
- [SQL.js Documentation](https://sql.js.org/)
- [Web Storage API Limitations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API#Storage_limits)

## Approval

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