email-organizer/docs/design/development-setup.md

Development Setup

This document describes how to set up a development environment for the Email Organizer application.

Prerequisites

• Docker and Docker Compose
• Python 3.10+
• Flask CLI tools

Project Structure

The application follows a modular structure:

app/
├── __init__.py          # Flask app factory and configuration
├── models.py            # Database models (User, Folder, ProcessedEmail)
├── auth.py              # Authentication blueprint
├── routes.py            # Main blueprint with sub-blueprints
├── imap_service.py      # IMAP communication service
├── processed_emails_service.py  # Email processing tracking
└── routes/              # Sub-blueprint modules
    ├── __init__.py
    ├── emails.py        # Email processing endpoints
    ├── folders.py       # Folder management endpoints
    └── imap.py          # IMAP configuration and sync endpoints

templates/              # Jinja2 templates with HTMX integration
static/                 # Static assets
config.py               # Application configuration

Services

The development environment consists of two services:

1. PostgreSQL Database: A non-persistent PostgreSQL instance for development
2. IMAP Server: A fake IMAP server with predefined users and folders

Setup Commands

To set up the development environment, run:

flask setup-dev

This command will:

1. Create necessary directories
2. Start PostgreSQL and IMAP services via Docker Compose
3. Display connection information

Service Details

PostgreSQL

• Host: localhost
• Port: 5432
• Database: email_organizer_dev
• User: postgres
• Password: password

IMAP Server

• Host: localhost
• Port: 5143
• Users:
  • user1@example.com / password1
  • user2@example.com / password2
• Folders:
  • INBOX
  • Pending
  • Work
  • Personal
  • Receipts
  • Marketing
  • Archived

Environment Configuration

After running flask setup-dev, copy the example environment file:

cp .env.example .env

The default configuration should work with the development services. You can modify the .env file if needed.

Configuration File

The config.py file provides different environment configurations:

class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY') or 'dev-secret-key'
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL') or 'postgresql://postgres:password@localhost:5432/email_organizer_dev'
    SQLALCHEMY_TRACK_MODIFICATIONS = False

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = 'sqlite:///:memory:'  # In-memory database for tests

Database Setup

The application uses Alembic for database migrations:

# Create migration
flask db migrate -m "Initial migration"

# Apply migration
flask db upgrade

Running the Application

# Development server
flask run

# With specific host and port
flask run --host=0.0.0.0 --port=5001

The application will be available at http://localhost:5001

Testing

The application includes comprehensive tests:

# Run all tests
pytest

# Run with coverage
pytest --cov=app

# Run specific test file
pytest tests/unit/test_auth.py

# Run integration tests
pytest tests/integration/

Test Structure

• Unit Tests: Test individual components and services
• Integration Tests: Test API endpoints and database interactions
• Functional Tests: Test user workflows and UI interactions

Development Workflow

1. Setup Environment: Run flask setup-dev to start services
2. Configure Database: Run migrations to set up database schema
3. Run Application: Start Flask development server
4. Test Changes: Write tests for new features
5. Commit Changes: Follow conventional commit messages

Key Technologies

• Backend: Flask, SQLAlchemy, PostgreSQL
• Frontend: HTMX, Alpine.js, DaisyUI, TailwindCSS
• Database: PostgreSQL with Alembic migrations
• Testing: pytest with Beautiful Soup for HTML testing
• Development: Docker for services, Flask CLI for management

Current Implementation Status

Core Features

• User authentication and session management ✅
• IMAP configuration and connection testing ✅
• Folder synchronization with type assignment ✅
• Email processing status tracking ✅
• HTMX-based UI with modals and dialogs ✅
• Folder type management (Tidy, Destination, Ignore) ✅

Development Tools

• Database migrations with Alembic ✅
• Comprehensive test suite ✅
• Docker-based development environment ✅
• Flask CLI for development tasks ✅
• Environment-based configuration ✅