# sachnaror/email_shooter architecture

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

- Interactive diagram: https://gitdiagram.com/sachnaror/email_shooter
- Repository: https://github.com/sachnaror/email_shooter

## Overview

##### Project Type and Purpose
- This is a Django‐based backend automation tool (“The Ultimate Email Ninja”) whose sole purpose is to send personalized, tracked emails in scheduled batches. It leverages:
- Django (email_shooter project + app1 Django app)
- Celery workers (asynchronous task queue)
- Redis (broker + potential runtime store)
- OpenAI API (dynamic content)
- Mailgun (SMTP/email sending via rotating proxies)
- Simple file stores (email_ids.txt, email_content.txt)
- No traditional “frontend” beyond a small Django view to trigger email sends and serve the tracking pixel.

##### File Structure
- Top level
- manage.py – Django CLI entrypoint
- requirements.txt – Python dependencies
- dump.rdb – Redis data dump
- email_ids.txt, email_content.txt – input data files
- test_send_email.py – end‐to‐end test
- email_shooter/ (Django project)
- asgi.py, wsgi.py – server interfaces
- celery_app.py – Celery configuration & beat scheduling
- urls.py – endpoint mappings
- app1/ (Django app)
- tasks.py – Celery tasks: read files, call OpenAI, send emails, cleanup
- views.py – HTTP views: start_email_sending endpoint & tracking pixel handler
- models.py – DB models for logs & open‐tracking
- utils.py – helper routines: dynamic content generation, random sender selection
- migrations/ – DB schema
- Celery + Redis handle scheduling and queueing, Django handles web endpoints & persistence.

##### Extracted Architecture Insights from README
- Core flow:
1. Trigger “start_email_sending” via HTTP
2. Celery beat schedules recurring send tasks every 6h
3. Task reads email IDs & content from flat files
4. Calls OpenAI to vary content & subject
5. Randomly selects Mailgun sender + proxy IP
6. Dispatches email, logs to models (DB)
7. Embeds tracking pixel URL pointing to a Django view
8. If recipient never opens, they’re pruned from the list
- External dependencies: OpenAI, Mailgun API, proxy services

##### Essential Details
- “6-hour” periodic schedule on Celery Beat
- “max 50 emails/day” rule near task logic
- “prune non-openers” step between tracking and next batch
- Paths: /start_email_sending/, /track/<id>

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Classes
    classDef internal fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef data fill:#D5F5E3,stroke:#28B463,color:#145A32
    classDef external fill:#FDEBD0,stroke:#D68910,color:#7E5109

    %% Actors
    Dev("Developer Browser"):::external
    Recip("Recipient Email Client"):::external

    %% Web Layer
    subgraph "Web Layer"
        WS["Django Web\n(email_shooter + app1)"]:::internal
        Start["HTTP POST /start_email_sending/"]:::internal
        Track["HTTP GET /track/&lt;pixel_id&gt;/"]:::internal
    end

    %% Worker Layer
    subgraph "Worker Layer"
        Beat["Celery Beat\n(6h schedule)"]:::internal
        Worker["Celery Worker\napp1.tasks"]:::internal
    end

    %% Data Layer
    subgraph "Data Layer"
        REDIS["Redis\n(broker/cache)"]:::data
        DB["Relational DB\n(Django Models)"]:::data
        IDs["email_ids.txt"]:::data
        Content["email_content.txt"]:::data
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Mailgun["Mailgun SMTP/API"]:::external
        Proxy["Proxy IP Pool"]:::external
    end

    %% Code Base
    subgraph "Code Base"
        MP["manage.py"]:::internal
        REQ["requirements.txt"]:::internal
        DUMP["dump.rdb"]:::data
        TEST["test_send_email.py"]:::internal
        ASGI["email_shooter/asgi.py"]:::internal
        WSGI["email_shooter/wsgi.py"]:::internal
        CELAPP["email_shooter/celery_app.py"]:::internal
        URLS["email_shooter/urls.py"]:::internal
        TASKS["app1/tasks.py"]:::internal
        VIEWS["app1/views.py"]:::internal
        MODELS["app1/models.py"]:::internal
        UTILS["app1/utils.py"]:::internal
        ADMIN["app1/admin.py"]:::internal
        APPS["app1/apps.py"]:::internal
        MIG["app1/migrations/"]:::internal
    end

    %% Connections
    Dev -->|POST start| Start
    Start -->|enqueue task| REDIS
    REDIS <-->|consume task| Worker
    Beat -->|schedule send_emails every 6h| REDIS
    Worker -->|read files| IDs
    Worker -->|read files| Content
    Worker -->|generate content| OpenAI
    Worker -->|select proxy & sender| Proxy
    Worker -->|send email| Mailgun
    Worker -->|write logs| DB
    Worker -->|prune non-openers| IDs
    Mailgun -->|delivers email| Recip
    Recip -->|opens email| Track
    Track -->|update opened flag| DB
    DB -->|next prune check| Worker

    %% Code Base click events
    click MP "https://github.com/sachnaror/email_shooter/blob/main/manage.py"
    click REQ "https://github.com/sachnaror/email_shooter/blob/main/requirements.txt"
    click DUMP "https://github.com/sachnaror/email_shooter/blob/main/dump.rdb"
    click TEST "https://github.com/sachnaror/email_shooter/blob/main/test_send_email.py"
    click ASGI "https://github.com/sachnaror/email_shooter/blob/main/email_shooter/asgi.py"
    click WSGI "https://github.com/sachnaror/email_shooter/blob/main/email_shooter/wsgi.py"
    click CELAPP "https://github.com/sachnaror/email_shooter/blob/main/email_shooter/celery_app.py"
    click URLS "https://github.com/sachnaror/email_shooter/blob/main/email_shooter/urls.py"
    click TASKS "https://github.com/sachnaror/email_shooter/blob/main/app1/tasks.py"
    click VIEWS "https://github.com/sachnaror/email_shooter/blob/main/app1/views.py"
    click MODELS "https://github.com/sachnaror/email_shooter/blob/main/app1/models.py"
    click UTILS "https://github.com/sachnaror/email_shooter/blob/main/app1/utils.py"
    click ADMIN "https://github.com/sachnaror/email_shooter/blob/main/app1/admin.py"
    click APPS "https://github.com/sachnaror/email_shooter/blob/main/app1/apps.py"
    click MIG "https://github.com/sachnaror/email_shooter/tree/main/app1/migrations/"

    %% Styles
    class Dev,Recip external
    class WS,Start,Track,Beat,Worker,MP,REQ,TASKS,VIEWS,MODELS,UTILS,ADMIN,APPS internal
    class REDIS,DB,IDs,Content,DUMP data
    class OpenAI,Mailgun,Proxy external
```
