184 lines
4.6 KiB
Markdown
184 lines
4.6 KiB
Markdown
# 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 ✅ |