notid/email-organizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Bryce
2025-08-06 10:30:20 -07:00
parent e6c8388ba6
commit 5336c04444
3 changed files with 101 additions and 756 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
README.md
View File

@@ -1,23 +1,25 @@
# Email Organizer
A self-hosted AI-powered email organization system that automates folder sorting, prioritization, and rule recommendations through natural language configuration.
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 sieve/filter rules
- **Smart Separation**: Automatically categorize marketing emails, receipts, and transactional messages
- **Adaptive Intelligence**: Learns your preferences to star important emails and suggest new organizational patterns
- **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
- AI: OpenAI-compatible API endpoints
- IMAP: Direct server integration
**Key Components**:
1. **Rule Engine**: Converts natural language rules → executable classification logic
2. **Email Processor**: Polls IMAP server, applies AI classifications, moves messages
3. **Recommendation System**: Analyzes usage patterns to suggest new folders/rules
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
@@ -44,41 +46,97 @@ flask db upgrade
flask run
```
## Roadmap
### Milestone 1: Prototype (Current Focus)
- [ ] Core infrastructure setup
- [ ] Basic UI for rule configuration
- [ ] Mock email processing pipeline
- [ ] Database schema implementation
## Features
### Future Milestones
- [ ] MVP - enter your imap server. You list out folders and rules, and once a day emails in the "Pending" folder will be reorganized.
- [ ] "Import" your list of folders from your imap server
- [ ] Polling every 5 minutes, working off recent emails since last poll
- [ ] Label support for services like gmail
- [ ] Generate config to automate integration into imap servers like dovecot or gmail or proton
- [ ] Supporting auth / multi user. Admin controls the list of users, users control their folders.
- [ ] Making a paid, hosted version
- [ ] Auth via google / facebook / etc.
- [ ] Automatically star based off of your habits
### 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 | UUID | Primary key |
| email | VARCHAR | Unique identifier |
| password_hash | BYTEA | Argon2-hashed |
| imap_config | JSONB | Encrypted server settings |
| 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 | UUID | Primary key |
| user_id | UUID | Foreign key |
| name | VARCHAR | Display name |
| rule_text | TEXT | Natural language rule |
| priority | INT | Processing order |
| 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
@@ -87,4 +145,10 @@ flask run
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.
> **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)