# Research: Relational Document System for Neovim

## SQLite Integration
**Decision**: Use lsqlite3 for SQLite database operations
**Rationale**: lsqlite3 is the most mature and widely used SQLite binding for Lua, with excellent Neovim compatibility and minimal dependencies
**Alternatives considered**:
- lua-sqlite3 (less mature, fewer updates)
- Custom file-based indexing (limited query capabilities)

## YAML Parsing
**Decision**: Use lyaml for YAML header parsing
**Rationale**: lyaml provides robust YAML parsing with proper error handling for malformed headers, essential for document reliability
**Alternatives considered**:
- Custom regex parsing (brittle, fails with complex YAML)
- yaml.lua (less maintained than lyaml)

## Virtual Buffer Management
**Decision**: Use Neovim's native nvim_buf_ API
**Rationale**: Native API provides the most seamless integration with Neovim's buffer system, ensuring compatibility with existing plugins and user workflows
**Alternatives considered**:
- Floating windows (less persistent, not ideal for editing)
- External terminal buffers (breaks Neovim integration)

## Query Syntax Design
**Decision**: Custom block syntax similar to code blocks
**Rationale**: Block syntax is familiar to markdown users and provides clear delimiters for query parsing while maintaining readability
**Alternatives considered**:
- Inline syntax (cluttered, hard to parse)
- Special comments (not intuitive for query visualization)

## Performance Optimization
**Decision**: Hybrid indexing approach (SQLite + in-memory cache)
**Rationale**: SQLite provides persistent storage and complex query capabilities, while in-memory caching ensures sub-100ms response times for frequently accessed data
**Alternatives considered**:
- Pure file-based indexing (slow for large document sets)
- Pure in-memory (data loss on restart)

## Testing Framework
**Decision**: busted with nvim-test plugin
**Rationale**: busted provides comprehensive testing capabilities with good async support, while nvim-test enables Neovim-specific testing scenarios
**Alternatives considered**:
- luaunit (limited Neovim integration)
- Custom testing harness (maintenance overhead)