mail2couch/docs/TODO.md

# mail2couch Development Roadmap

*Last Updated: August 2025*

This document outlines the development roadmap for mail2couch, with both Go and Rust implementations now in production-ready status.

## ✅ Completed Major Milestones

### Production Readiness (August 2025)
- ✅ **Full Feature Parity**: Both implementations provide identical functionality
- ✅ **Server-side IMAP SEARCH**: Keyword filtering implemented in both Go and Rust
- ✅ **Binary Attachment Support**: Verified working with CouchDB native attachments
- ✅ **Incremental Sync**: Cross-implementation compatibility verified
- ✅ **Dry-run Mode**: Comprehensive testing capabilities in both implementations
- ✅ **Error Handling**: Robust retry logic and graceful fallbacks
- ✅ **SystemD Integration**: Timer units for automated scheduling
- ✅ **Build System**: Unified justfile for both implementations
- ✅ **Documentation**: Comprehensive guides and comparisons
- ✅ **Code Quality**: All linting and formatting standards met

### Architecture & Testing
- ✅ **Database Output Equivalence**: Both implementations produce identical CouchDB documents
- ✅ **Filtering Accuracy**: Server-side IMAP LIST and SEARCH with client-side fallbacks
- ✅ **Connection Handling**: TLS support, automatic retry, graceful error recovery
- ✅ **Configuration Management**: Automatic file discovery, validation, GNU-style CLI

### Originally Planned Features (Now Complete)
- ✅ **Keyword Filtering for Messages**: Subject, sender, and recipient keyword filtering implemented
- ✅ **Real IMAP Message Parsing**: Full message content extraction with go-message and mail-parser
- ✅ **Message Body Extraction**: HTML/plain text and multipart message support
- ✅ **Attachment Handling**: Complete binary attachment support with CouchDB native storage
- ✅ **Error Recovery**: Comprehensive retry logic and partial sync recovery
- ✅ **Performance**: Batch operations and efficient CouchDB insertion

## 🚧 Current Development Priorities

### Recently Completed ✅
1. **🔐 Enhanced Security Model**
   - ✅ Environment variable credential support (`MAIL2COUCH_IMAP_PASSWORD`, etc.)
   - ✅ Eliminate plaintext passwords from configuration files
   - ✅ Comprehensive documentation and help integration
   - ❌ System keyring integration for credential storage (future enhancement)

### High Priority

### Medium Priority
2. **🚀 Go Implementation Concurrency**
   - Optional goroutine-based parallel mailbox processing
   - Maintain simplicity while improving performance for multiple accounts
   - Configurable concurrency levels

3. **📊 Progress Indicators**
   - Real-time progress reporting for long-running operations
   - ETA calculations for large mailbox synchronization
   - Progress bars for terminal output

4. **🖥️ Interactive Setup**
   - Guided configuration wizard (`mail2couch setup`)
   - Interactive validation of IMAP and CouchDB connectivity
   - Generate sample configurations for common providers

### Low Priority
5. **📈 Performance Metrics**
   - Built-in timing and throughput reporting
   - Memory usage monitoring
   - Network efficiency statistics

6. **🔄 Advanced Sync Features**
   - Bidirectional sync capabilities
   - Conflict resolution strategies
   - Message modification detection

7. **🌐 Web Interface**
   - Optional web UI for configuration and monitoring
   - CouchDB view integration for email browsing
   - Search interface for archived emails

8. **📱 API Integration**
   - REST API for external system integration
   - Webhook support for sync completion notifications
   - Monitoring system integration

## 📋 Technical Debt & Improvements

### Code Quality
- **Unit Test Coverage**: Expand test coverage for both implementations
- **Integration Testing**: Automated testing with various IMAP servers
- **Performance Benchmarking**: Standardized performance comparison tools

### User Experience
- **Error Messages**: More descriptive error messages with suggested solutions
- **Configuration Validation**: Enhanced validation with helpful error descriptions
- **Logging**: Structured logging with different verbosity levels

### Security
- **OAuth2 Support**: Modern authentication for Gmail, Outlook, etc.
- **Credential Encryption**: Encrypt stored credentials at rest
- **Audit Logging**: Enhanced logging of authentication and access events

## 🎯 Release Planning

### Next Minor Release (v1.1)
- Environment variable credential support
- Interactive setup command
- Enhanced error messages

### Next Major Release (v2.0)
- OAuth2 authentication support
- Web interface (optional)
- Go implementation concurrency improvements

## 📊 Implementation Status

| Feature Category | Go Implementation | Rust Implementation | Priority |
|-----------------|------------------|-------------------|----------|
| **Core Features** | ✅ Complete | ✅ Complete | - |
| **Security Model** | ⚠️ Basic | ⚠️ Basic | High |
| **Concurrency** | ⚠️ Sequential | ✅ Async | Medium |
| **Progress Reporting** | ⚠️ Basic | ⚠️ Basic | Medium |
| **Interactive Setup** | ❌ Missing | ❌ Missing | Medium |
| **Web Interface** | ❌ Missing | ❌ Missing | Low |

## 🤝 Contributing

### Areas Needing Contribution
1. **Security Features**: OAuth2 implementation, credential encryption
2. **User Experience**: Interactive setup, progress indicators
3. **Testing**: Unit tests, integration tests, performance benchmarks
4. **Documentation**: Usage examples, troubleshooting guides

### Development Guidelines
- Maintain feature parity between Go and Rust implementations
- Follow established code quality standards (linting, formatting)
- Include comprehensive testing for new features
- Update documentation with new functionality

## 📝 Notes

### Design Decisions
- **Two Implementations**: Maintain both Go (simplicity) and Rust (performance) versions
- **Configuration Compatibility**: Ensure identical configuration formats
- **Database Compatibility**: Both implementations must produce identical CouchDB output

### Long-term Vision
- Position Go implementation for personal/small-scale use
- Position Rust implementation for enterprise/large-scale use
- Maintain migration path between implementations
- Focus on reliability and data integrity above all else