Getting Started Architecture Overview - onouyek/MailApe GitHub Wiki

Architecture Overview

MailApe is built as a Django web application with a task queue system for handling email delivery.

High-Level Architecture

graph TB
    User[Users] --> Web[Django Web Application]
    Web --> DB[(PostgreSQL Database)]
    Web --> Queue[Celery Task Queue]
    Queue --> Redis[(Redis)]
    Queue --> Email[Email Delivery]
    
    subgraph "Django Apps"
        Web --> ML[mailinglist app]
        Web --> U[user app]
    end
    
    subgraph "Background Processing"
        Queue --> Tasks[Email Tasks]
        Tasks --> SMTP[SMTP Server]
    end

Core Components

1. Django Web Application

  • Framework: Django 3.x
  • Purpose: Web interface, API, and business logic
  • Apps: mailinglist (core functionality) and user (authentication)

Source: common_settings.py#L33-46

2. PostgreSQL Database

  • Purpose: Primary data storage
  • Schema: Mailing lists, subscribers, messages, and user data
  • Configuration: Uses Django ORM for database interactions

Source: common_settings.py#L82

3. Celery Task Queue

  • Purpose: Asynchronous email processing
  • Broker: Redis
  • Result Backend: Django database
  • Tasks: Email confirmation, message distribution

Source: common_settings.py#L123

4. Redis

  • Purpose: Message broker for Celery
  • Configuration: Used for task queue management

Source: requirements.common.txt#L6

Application Flow

User Registration Flow

sequenceDiagram
    participant U as User
    participant W as Web App
    participant DB as Database
    participant C as Celery
    participant E as Email System
    
    U->>W: Subscribe to mailing list
    W->>DB: Create Subscriber (confirmed=False)
    DB->>C: Trigger confirmation email task
    C->>E: Send confirmation email
    U->>W: Click confirmation link
    W->>DB: Update subscriber (confirmed=True)

Message Sending Flow

sequenceDiagram
    participant O as List Owner
    participant W as Web App
    participant DB as Database
    participant C as Celery
    participant E as Email System
    
    O->>W: Create message
    W->>DB: Save message
    DB->>C: Trigger build subscriber messages
    C->>DB: Create SubscriberMessage for each confirmed subscriber
    DB->>C: Trigger send tasks for each message
    C->>E: Send individual emails

Data Model Overview

Core Models

  1. MailingList

    • Owned by a user
    • Contains subscribers and messages
    • UUID primary key

  2. Subscriber

    • Email address and confirmation status
    • Belongs to a mailing list
    • Unique constraint on email + mailing list

  3. Message

    • Subject and body content
    • Belongs to a mailing list
    • Tracks sending status

  4. SubscriberMessage

    • Individual email delivery record
    • Links message to specific subscriber
    • Tracks delivery attempts and status

Source: models.py

Technology Stack

Backend

  • Django 3.x: Web framework
  • PostgreSQL: Primary database
  • Celery: Task queue
  • Redis: Message broker
  • Django REST Framework: API functionality

Frontend

  • Django Templates: Server-side rendering
  • Bootstrap 4: UI framework (via Crispy Forms)
  • Django Crispy Forms: Form rendering

Infrastructure

  • AWS RDS: Managed PostgreSQL
  • AWS SQS: Message queue (production)
  • AWS EC2: Application hosting

Source: requirements.common.txt and infrastructure.yaml

Security Model

  • Authentication: Django's built-in user system
  • Authorization: Owner-based access control
  • CSRF Protection: Enabled by default
  • Rate Limiting: API throttling via DRF

Source: common_settings.py#L125-132

Next Steps