# paulledemon/email-automation architecture

> Architecture diagram of the GitHub repository paulledemon/email-automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paulledemon/email-automation
- Repository: https://github.com/paulledemon/email-automation

## Overview

##### Project Type and Purpose
- This is a full-stack, open-source email automation (cold outreach) tool built on Django (MVT pattern).
- It combines a web UI (templates + static assets), a REST/API layer, a relational database, and asynchronous background processing (Celery + Redis) to schedule and send personalized bulk emails via external SMTP/IMAP services.

##### Main Components
a. Client Layer (Browser)
- Loads HTML/CSS/JS (Django templates, staticfiles, theme assets).
- Executes client-side validation via Nunjucks and dynamically loads content (email templates, campaign UIs).
b. Web Application Layer (Django)
- URL routing (email_automation/urls.py, automail/urls.py, user/urls.py, blog/urls.py).
- Views/Controllers (email_automation/views.py, automail/views.py, etc.).
- Templates (Jinja2 for email rendering; Django templates for UI).
- Static Assets (Tailwind-generated CSS, JS modules under staticfiles/ and theme/static/).
- Admin site (automail/admin.py, blog/admin.py, user/admin.py) for configuration.
c. Data Layer (PostgreSQL)
- Persistent storage for users, templates, campaigns, configurations, follow-up rules.
- Django ORM models (in automail/models.py, user/models.py, blog/models.py).
d. Messaging Layer
- Message broker & scheduler (Redis).
- Beat scheduler via django_celery_beat (storing schedule entries in the DB).
e. Background Workers
- Celery workers (tasks defined in utils/tasks.py, automail/signals.py triggers).
- Send emails asynchronously, query the database, update campaign status.
f. External Services
- SMTP/IMAP servers (third-party email providers or self-hosted).
- Optional: Firebase for push notifications (if configured).

##### Relationships & Data Flows
- Browser → HTTP(s) → Django Web Server → Database (read/write)
- Django schedules jobs → Redis (broker) → Celery Beat → Celery Worker
- Celery Worker → Database (update status)
- Celery Worker → External SMTP/IMAP → Recipient Mailboxes
- Django → External Email Services (on-demand sends / config tests)

##### Architectural Patterns & Principles
- Django MVT (separate models, views/controllers, templates).
- Asynchronous task queue (Celery) for long-running email sends and follow-ups.
- Scheduler (django_celery_beat) for periodic tasks (follow-up rules).
- Modular “apps” structure (automail, user, blog, theme).
- Configuration via environment variables (.env in email_automation/settings.py).

##### Technologies to Annotate
- Backend: Python 3.8+, Django, Celery, django_celery_beat, Jinja2 (email rendering).
- Frontend: Django templates, static JS (Nunjucks validation), Tailwind CSS.
- Data Store: PostgreSQL.
- Broker/Cache: Redis.
- Deployment: WSGI/ASGI (gunicorn/daphne), Procfile (e.g., Heroku), possible Vercel/Render/Railway.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser(("Browser")):::browser
    Browser -->|"loads HTML/CSS/JS"| TemplatesDir
    Browser -->|"loads static assets"| StaticDir
    Browser -->|"loads theme assets"| ThemeStatic

    %% Django Web Application Layer
    subgraph "Django Web App" 
        direction TB
        subgraph "URL Routing"
            direction TB
            URLsProj["email_automation/urls.py"]:::webapp
            URLsAuto["automail/urls.py"]:::webapp
            URLsUser["user/urls.py"]:::webapp
            URLsBlog["blog/urls.py"]:::webapp
        end
        subgraph "Views/Controllers"
            direction TB
            ViewsProj["email_automation/views.py"]:::webapp
            ViewsAuto["automail/views.py"]:::webapp
            ViewsUser["user/views.py"]:::webapp
            ViewsBlog["blog/views.py"]:::webapp
        end
        subgraph "Admin Site"
            direction TB
            AdminAuto["automail/admin.py"]:::webapp
            AdminUser["user/admin.py"]:::webapp
            AdminBlog["blog/admin.py"]:::webapp
        end
        subgraph "Settings & Config"
            direction TB
            Settings["email_automation/settings.py"]:::webapp
            CeleryConf["email_automation/celery.py"]:::webapp
            Middleware["email_automation/middlewares.py"]:::webapp
            ContextProc["email_automation/context_processors.py"]:::webapp
        end
        CustomTags["email_automation/templatetags/custom_tags.py"]:::webapp
        subgraph "Templates & Static"
            direction TB
            TemplatesDir["templates/"]:::frontend
            StaticDir["staticfiles/static/"]:::frontend
            ThemeStatic["theme/static/"]:::frontend
            ThemeTpl["theme/templates/base.html"]:::frontend
        end
    end

    %% Data Layer
    DB[(PostgreSQL)]:::database

    %% Messaging Layer & Scheduler
    Redis[(Redis Broker)]:::broker

    %% Background Workers
    CeleryWorker["Celery Workers"]:::worker

    %% External Services
    SMTP(["SMTP/IMAP Providers"]):::external

    %% Data Flows
    Browser -->|"HTTP(S) request"| URLsProj
    URLsProj --> ViewsProj
    URLsAuto --> ViewsAuto
    URLsUser --> ViewsUser
    URLsBlog --> ViewsBlog

    ViewsProj -->|ORM read/write| DB
    ViewsAuto -->|ORM read/write| DB
    ViewsUser -->|ORM read/write| DB
    ViewsBlog -->|ORM read/write| DB

    ViewsAuto -->|"dispatch task"| Redis
    CeleryWorker -->|message delivery| Redis

    CeleryWorker -->|update campaign state| DB
    CeleryWorker -->|SMTP send| SMTP

    ViewsProj -->|on-demand email/test| SMTP

    %% Click Events
    click TemplatesDir "https://github.com/paulledemon/email-automation/tree/master/templates/"
    click StaticDir "https://github.com/paulledemon/email-automation/tree/master/staticfiles/static/"
    click ThemeStatic "https://github.com/paulledemon/email-automation/tree/master/theme/static/"
    click ThemeTpl "https://github.com/paulledemon/email-automation/blob/master/theme/templates/base.html"
    click URLsProj "https://github.com/paulledemon/email-automation/blob/master/email_automation/urls.py"
    click URLsAuto "https://github.com/paulledemon/email-automation/blob/master/automail/urls.py"
    click URLsUser "https://github.com/paulledemon/email-automation/blob/master/user/urls.py"
    click URLsBlog "https://github.com/paulledemon/email-automation/blob/master/blog/urls.py"
    click ViewsProj "https://github.com/paulledemon/email-automation/blob/master/email_automation/views.py"
    click ViewsAuto "https://github.com/paulledemon/email-automation/blob/master/automail/views.py"
    click ViewsUser "https://github.com/paulledemon/email-automation/blob/master/user/views.py"
    click ViewsBlog "https://github.com/paulledemon/email-automation/blob/master/blog/views.py"
    click AdminAuto "https://github.com/paulledemon/email-automation/blob/master/automail/admin.py"
    click AdminUser "https://github.com/paulledemon/email-automation/blob/master/user/admin.py"
    click AdminBlog "https://github.com/paulledemon/email-automation/blob/master/blog/admin.py"
    click Settings "https://github.com/paulledemon/email-automation/blob/master/email_automation/settings.py"
    click CeleryConf "https://github.com/paulledemon/email-automation/blob/master/email_automation/celery.py"
    click Middleware "https://github.com/paulledemon/email-automation/blob/master/email_automation/middlewares.py"
    click ContextProc "https://github.com/paulledemon/email-automation/blob/master/email_automation/context_processors.py"
    click CustomTags "https://github.com/paulledemon/email-automation/blob/master/email_automation/templatetags/custom_tags.py"

    %% Styles
    classDef browser fill:#B3E5FC,stroke:#0288D1,color:#000
    classDef frontend fill:#FFF9C4,stroke:#FBC02D,color:#000
    classDef webapp fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef database fill:#FFCCBC,stroke:#D84315,color:#000
    classDef broker fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef worker fill:#D1C4E9,stroke:#5E35B1,color:#000
    classDef external fill:#CFD8DC,stroke:#455A64,color:#000
```
