# 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:

```bash
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:

```bash
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`](config.py:1) file provides different environment configurations:

```python
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:

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

# Apply migration
flask db upgrade
```

## Running the Application

```bash
# 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:

```bash
# 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 ✅