mail2couch/docs/README.md

# mail2couch Documentation

This directory contains comprehensive documentation for the mail2couch project, which provides two production-ready implementations for backing up mail from IMAP servers to CouchDB.

## 📚 Documentation Index

### Core Documentation
- **[ANALYSIS.md](ANALYSIS.md)** - Detailed technical analysis of both implementations
- **[IMPLEMENTATION_COMPARISON.md](IMPLEMENTATION_COMPARISON.md)** - Side-by-side comparison of Go vs Rust implementations
- **[couchdb-schemas.md](couchdb-schemas.md)** - CouchDB document schemas and database structure
- **[TODO.md](TODO.md)** - Development roadmap and outstanding tasks

### Configuration & Setup
- **[ENVIRONMENT_VARIABLES.md](ENVIRONMENT_VARIABLES.md)** - Complete guide to environment variable credential overrides
- **[FOLDER_PATTERNS.md](FOLDER_PATTERNS.md)** - Guide to folder filtering patterns and wildcards
- **[test-config-comparison.md](test-config-comparison.md)** - Configuration examples and testing scenarios

### Examples
- **[examples/](examples/)** - Sample CouchDB documents and configuration files
  - `sample-mail-document.json` - Complete email document with attachments
  - `sample-sync-metadata.json` - Sync state tracking document
  - `simple-mail-document.json` - Basic email document structure

## 🚀 Quick Start

Both implementations are production-ready with identical feature sets:

### Go Implementation
```bash
cd go && go build -o mail2couch-go .
./mail2couch-go --config ../config.json --dry-run
```

### Rust Implementation  
```bash
cd rust && cargo build --release
./target/release/mail2couch-rs --config ../config.json --dry-run
```

## ✅ Current Status (August 2025)

Both implementations are **production-ready** with:

- ✅ **Full IMAP support** with TLS/SSL connections
- ✅ **Server-side folder filtering** using IMAP LIST patterns
- ✅ **Server-side message filtering** using IMAP SEARCH with keyword support
- ✅ **Binary attachment handling** with CouchDB native attachments
- ✅ **Incremental synchronization** with metadata tracking
- ✅ **Sync vs Archive modes** for different backup strategies
- ✅ **Dry-run mode** for safe testing
- ✅ **Comprehensive error handling** with graceful fallbacks
- ✅ **SystemD integration** with timer units for automated scheduling
- ✅ **Build system integration** with justfile for unified project management

## 🔧 Key Features

### Filtering & Search
- **Folder Filtering**: Wildcard patterns (`*`, `?`, `[abc]`) with include/exclude lists
- **Message Filtering**: Subject, sender, and recipient keyword filtering
- **IMAP SEARCH**: Server-side filtering when supported, client-side fallback
- **Date Filtering**: Incremental sync based on last sync time or configured since date

### Data Storage
- **CouchDB Integration**: Native attachment storage, per-account databases
- **Document Structure**: Standardized schema with full email metadata
- **Sync Metadata**: State tracking for efficient incremental updates
- **Duplicate Prevention**: UID-based deduplication across syncs

### Operations
- **Mode Selection**: Archive (append-only) or Sync (mirror) modes
- **Connection Handling**: Automatic retry logic, graceful error recovery
- **Progress Reporting**: Detailed logging with message counts and timing
- **Resource Management**: Configurable message limits, connection pooling

## 📊 Performance & Compatibility

Both implementations have been tested with:
- **IMAP Servers**: Gmail, Office365, Dovecot, GreenMail
- **CouchDB Versions**: 3.x with native attachment support
- **Message Volumes**: Tested with thousands of messages and large attachments
- **Network Conditions**: Automatic retry and reconnection handling

## 🛠️ Development

See individual implementation directories for development setup:
- **Go**: `/go/` - Standard Go toolchain with modules
- **Rust**: `/rust/` - Cargo-based build system with comprehensive testing

For unified development commands, use the project justfile:
```bash
just build    # Build both implementations
just test     # Run all tests
just check    # Run linting and formatting
just install  # Install systemd services
```