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