email-organizer/README.md

# Email Organizer

A self-hosted email organization system that automates folder sorting and management through natural language configuration.

## Core Value Proposition
- **Natural Language Rules**: Define email organization logic in plain English instead of writing complex filter rules
- **Smart Separation**: Automatically categorize emails into custom folders based on your rules
- **IMAP Integration**: Sync and manage folders directly from your email server
- **User Authentication**: Secure multi-user system with individual configurations

## Technical Overview
**Stack**:
- Backend: Flask (Python 3.10+)
- Frontend: HTMX + AlpineJS + DaisyUI (Tailwind CSS)
- Database: PostgreSQL
- IMAP: Direct server integration

**Key Components**:
1. **Authentication System**: User registration, login, and session management
2. **Folder Management**: Create, edit, and organize email folders with natural language rules
3. **IMAP Service**: Direct integration with email servers for folder synchronization
4. **User Interface**: Modern, responsive UI with dynamic updates

## Getting Started
### Prerequisites
- Python 3.10+
- PostgreSQL 14+
- IMAP server access

### Setup
```bash
# Install dependencies
pip install -r requirements.txt

# Set up development environment (PostgreSQL and IMAP server)
flask setup-dev

# Configure environment
cp .env.example .env
# (Edit .env with your DB/IMAP credentials)

# Initialize database
flask db upgrade

# Run development server
flask run
```

## Features

### Current Implementation
- **User Authentication**: Complete user registration and login system with password validation
- **Folder Management**: Create, edit, delete, and toggle email organization folders
- **IMAP Integration**: Configure and test connections to email servers
- **Folder Synchronization**: Import existing folders from IMAP servers
- **Natural Language Rules**: Define organization rules in plain English
- **Priority System**: Organize folders with priority levels
- **Email Metrics**: Track email counts and recent email information

### User Interface
- **Modern Design**: Clean, responsive interface using DaisyUI
- **Dynamic Updates**: HTMX for seamless UI interactions without page reloads
- **Modal System**: Forms and configuration in intuitive modal dialogs
- **Real-time Feedback**: Immediate visual feedback for all operations

## Architecture
The application follows a modular architecture with clear separation of concerns:

- **Frontend Layer**: HTMX + AlpineJS + DaisyUI for dynamic user interface
- **Application Layer**: Flask blueprints for modular feature organization
- **Data Layer**: PostgreSQL with SQLAlchemy ORM for data persistence
- **Service Layer**: IMAP service for email server communication

For detailed architecture information, see [System Architecture](docs/design/system-architecture.md).

## Data Model
The system uses two main entities with a one-to-many relationship:

**Users**
| Column | Type | Description |
|--------|------|-------------|
| id | Integer | Primary key |
| first_name | String | User's first name |
| last_name | String | User's last name |
| email | String | Unique identifier |
| password_hash | String | Hashed password |
| imap_config | JSON | Server settings |
| created_at | DateTime | Account creation timestamp |
| updated_at | DateTime | Last update timestamp |

**Folders**
| Column | Type | Description |
|--------|------|-------------|
| id | Integer | Primary key |
| user_id | Integer | Foreign key to user |
| name | String | Display name |
| rule_text | Text | Natural language rule |
| priority | Integer | Processing order (0=normal, 1=high) |
| organize_enabled | Boolean | Rule active status |
| total_count | Integer | Total emails in folder |
| pending_count | Integer | Emails to process |
| recent_emails | JSON | Recent email metadata |
| created_at | DateTime | Folder creation timestamp |
| updated_at | DateTime | Last update timestamp |

For detailed data model information, see [Data Model](docs/design/data-model.md).

## Development Environment
The development environment includes:
- **PostgreSQL Database**: For data persistence
- **Dovecot IMAP Server**: For testing email integration
- **Docker Compose**: For easy service orchestration

### Development Services
- **Database**: localhost:5432 (email_organizer_dev)
- **IMAP Server**: localhost:1143
- **Test Users**: 
  - user1@example.com / password1
  - user2@example.com / password2

## Roadmap
### Current Status
- ✅ User authentication system
- ✅ Folder CRUD operations
- ✅ IMAP configuration and testing
- ✅ Folder synchronization from IMAP servers
- ✅ Natural language rule configuration
- ✅ Priority-based folder organization
- ✅ Email metrics tracking

### Future Enhancements
- **AI-Powered Rules**: Advanced rule processing and recommendations
- **Email Processing**: Automated email classification and movement
- **Advanced IMAP Features**: Two-factor authentication, OAuth support
- **Label Support**: Integration with Gmail and other providers
- **Admin Interface**: Multi-user management and monitoring
- **Hosted Service**: Cloud-based offering
- **Social Authentication**: Google, Facebook, etc. login options
- **Usage Analytics**: Email processing statistics and insights

## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

> **Note**: All new features require corresponding unit tests and documentation updates.

## Documentation
- [System Architecture](docs/design/system-architecture.md)
- [Data Model](docs/design/data-model.md)
- [IMAP Connectivity](docs/design/imap-connectivity.md)
- [Development Setup](docs/design/development-setup.md)