stateDiagram-v2
    [*] --> QUEUED: Email Created

    QUEUED --> SENDING: Worker Picks Up
    SENDING --> SENT: Accepted by Provider
    SENDING --> FAILED: Sending Error

    SENT --> DELIVERED: Delivery Confirmed
    SENT --> BOUNCED: Bounce Received
    SENT --> DEFERRED: Temporary Failure

    DEFERRED --> SENT: Retry Success
    DEFERRED --> BOUNCED: Retry Failed

    DELIVERED --> OPENED: Open Tracked
    DELIVERED --> [*]: No Engagement

    OPENED --> CLICKED: Link Clicked
    OPENED --> UNSUBSCRIBED: Unsubscribe
    OPENED --> SPAM: Marked as Spam

    BOUNCED --> [*]
    SPAM --> [*]
    FAILED --> [*]

    note right of SENT
        Provider accepted,
        pending delivery
    end note

    note right of BOUNCED
        Hard bounce = suppress
        Soft bounce = retry
    end note

sequenceDiagram
    participant App as Application
    participant Queue as Email Queue
    participant Worker as Email Worker
    participant Rate as Rate Limiter
    participant Provider as Email Provider
    participant DB as Database

    App->>Queue: Queue email
    Queue->>DB: Store email record (QUEUED)

    Worker->>Queue: Poll for emails
    Queue-->>Worker: Email batch

    loop For each email
        Worker->>Rate: Check rate limit
        Rate-->>Worker: Allowed/Throttled

        alt Throttled
            Worker->>Queue: Re-queue with delay
        else Allowed
            Worker->>Provider: Send email
            Provider-->>Worker: Response

            alt Accepted
                Worker->>DB: Update (SENT)
                Worker->>DB: Store messageId
            else Rejected
                Worker->>DB: Update (FAILED)
                Worker->>DB: Store error
            end
        end
    end

flowchart TD
    subgraph "Incoming Webhooks"
        SES[SES Notification]
        SMTP[SMTP Callback]
        RESEND[Resend Webhook]
    end

    subgraph "Webhook Handler"
        RECEIVE[Receive Webhook] --> VALIDATE[Validate Signature]
        VALIDATE --> PARSE[Parse Event]
        PARSE --> TYPE{Event Type?}
    end

    subgraph "Event Processing"
        TYPE -->|Delivery| DELIVERED[Mark Delivered]
        TYPE -->|Bounce| BOUNCE[Process Bounce]
        TYPE -->|Complaint| COMPLAINT[Process Complaint]
        TYPE -->|Open| OPEN[Track Open]
        TYPE -->|Click| CLICK[Track Click]
    end

    subgraph "Actions"
        BOUNCE --> BOUNCE_TYPE{Bounce Type?}
        BOUNCE_TYPE -->|Hard| SUPPRESS[Add to Suppression]
        BOUNCE_TYPE -->|Soft| RETRY[Schedule Retry]

        COMPLAINT --> SUPPRESS
        COMPLAINT --> UNSUB[Unsubscribe Contact]

        OPEN --> UPDATE[Update Email Record]
        CLICK --> UPDATE
        UPDATE --> ANALYTICS[Update Analytics]
    end

    SES --> RECEIVE
    SMTP --> RECEIVE
    RESEND --> RECEIVE

    style SUPPRESS fill:#ffebee

flowchart TD
    BOUNCE[Bounce Received] --> CLASSIFY{Classify Bounce}

    CLASSIFY -->|Hard Bounce| HARD[Hard Bounce]
    CLASSIFY -->|Soft Bounce| SOFT[Soft Bounce]

    subgraph "Hard Bounce Reasons"
        HARD --> H1[Invalid Address]
        HARD --> H2[Domain Not Found]
        HARD --> H3[User Unknown]
    end

    subgraph "Soft Bounce Reasons"
        SOFT --> S1[Mailbox Full]
        SOFT --> S2[Server Down]
        SOFT --> S3[Message Too Large]
        SOFT --> S4[Content Rejected]
    end

    H1 --> SUPPRESS[Suppress Email]
    H2 --> SUPPRESS
    H3 --> SUPPRESS

    S1 --> RETRY_QUEUE[Queue for Retry]
    S2 --> RETRY_QUEUE
    S3 --> FLAG[Flag for Review]
    S4 --> FLAG

    RETRY_QUEUE --> RETRY_COUNT{Retry Count?}
    RETRY_COUNT -->|< 3| RETRY[Retry Later]
    RETRY_COUNT -->|>= 3| SUPPRESS

    SUPPRESS --> UPDATE_CONTACT[Update Contact Status]
    UPDATE_CONTACT --> LOG[Log Suppression]

    style SUPPRESS fill:#ffebee

sequenceDiagram
    participant Email as Email Client
    participant Pixel as Tracking Pixel Server
    participant Service as Tracking Service
    participant DB as Database
    participant Analytics as Analytics

    Note over Email: User opens email

    Email->>Pixel: Load tracking pixel
    Note over Pixel: GET /track/open/{emailId}

    Pixel->>Service: processOpen(emailId)
    Service->>DB: Get email record
    DB-->>Service: Email data

    Service->>Service: Extract metadata
    Note over Service: IP, User Agent, Time

    alt First open
        Service->>DB: Update email (OPENED)
        Service->>DB: Set firstOpenedAt
    end

    Service->>DB: Create EmailEvent (OPEN)
    Service->>Analytics: Increment open count

    Pixel-->>Email: 1x1 transparent pixel

flowchart TD
    CLICK[User Clicks Link] --> REDIRECT[Tracking Redirect]

    REDIRECT --> PARSE[Parse Click Data]
    PARSE --> EXTRACT[Extract Email ID + Link ID]

    EXTRACT --> LOG[Log Click Event]
    LOG --> UPDATE[Update Email Record]
    UPDATE --> ANALYTICS[Update Analytics]

    ANALYTICS --> FORWARD[Redirect to Destination]

    subgraph "Click Data Captured"
        DATA1[Email ID]
        DATA2[Link URL]
        DATA3[Timestamp]
        DATA4[IP Address]
        DATA5[User Agent]
        DATA6[Device Type]
    end

    FORWARD --> DEST[Original URL]

    style FORWARD fill:#e8f5e9

flowchart LR
    subgraph "Real-Time Metrics"
        SENT_RT[Sent Now]
        DELIVER_RT[Delivered Now]
        OPEN_RT[Opened Now]
        BOUNCE_RT[Bounced Now]
    end

    subgraph "Aggregate Metrics"
        TOTAL_SENT[Total Sent]
        DELIVER_RATE[Delivery Rate]
        OPEN_RATE[Open Rate]
        CLICK_RATE[Click Rate]
        BOUNCE_RATE[Bounce Rate]
    end

    subgraph "Trends"
        HOURLY[Hourly Trend]
        DAILY[Daily Trend]
        WEEKLY[Weekly Comparison]
    end

    SENT_RT --> TOTAL_SENT
    DELIVER_RT --> DELIVER_RATE
    OPEN_RT --> OPEN_RATE
    BOUNCE_RT --> BOUNCE_RATE

    TOTAL_SENT --> HOURLY
    DELIVER_RATE --> DAILY
    OPEN_RATE --> WEEKLY

erDiagram
    EMAIL ||--o{ EMAIL_EVENT : logs
    EMAIL ||--o{ EMAIL_LINK_CLICK : tracks

    EMAIL_EVENT {
        string id PK
        string emailId FK
        enum eventType
        timestamp occurredAt
        string ipAddress
        string userAgent
        string deviceType
        string country
        string city
        json metadata
    }

    EMAIL_LINK_CLICK {
        string id PK
        string emailId FK
        string linkUrl
        string linkId
        timestamp clickedAt
        string ipAddress
        string userAgent
    }

    EMAIL_SUPPRESSION {
        string id PK
        string tenantId FK
        string email
        enum reason
        string source
        timestamp createdAt
        timestamp expiresAt
    }

flowchart TD
    subgraph "Health Indicators"
        BOUNCE_MON[Bounce Rate < 2%]
        COMPLAINT_MON[Complaint Rate < 0.1%]
        DELIVER_MON[Delivery Rate > 95%]
        ENGAGE_MON[Engagement Stable]
    end

    subgraph "Alerts"
        BOUNCE_MON --> CHECK_B{OK?}
        COMPLAINT_MON --> CHECK_C{OK?}
        DELIVER_MON --> CHECK_D{OK?}

        CHECK_B -->|No| ALERT_B[Bounce Alert]
        CHECK_C -->|No| ALERT_C[Complaint Alert]
        CHECK_D -->|No| ALERT_D[Delivery Alert]
    end

    subgraph "Actions"
        ALERT_B --> REVIEW[Review List Hygiene]
        ALERT_C --> UNSUB[Check Unsubscribe Process]
        ALERT_D --> INFRA[Check Infrastructure]
    end

    subgraph "Reputation"
        DOMAIN_REP[Domain Reputation]
        IP_REP[IP Reputation]
        SENDER_SCORE[Sender Score]
    end

    style ALERT_B fill:#ffebee
    style ALERT_C fill:#ffebee
    style ALERT_D fill:#ffebee

flowchart TD
    CONTACT[Contact] --> HISTORY[Email History]

    HISTORY --> METRICS[Calculate Metrics]

    METRICS --> OPENS[Open Rate]
    METRICS --> CLICKS[Click Rate]
    METRICS --> RECENCY[Last Engagement]
    METRICS --> FREQ[Engagement Frequency]

    OPENS --> SCORE[Engagement Score]
    CLICKS --> SCORE
    RECENCY --> SCORE
    FREQ --> SCORE

    SCORE --> SEGMENT{Score Range}
    SEGMENT -->|High| ACTIVE[Highly Engaged]
    SEGMENT -->|Medium| MODERATE[Moderately Engaged]
    SEGMENT -->|Low| AT_RISK[At Risk]
    SEGMENT -->|None| INACTIVE[Inactive]

    ACTIVE --> MORE[Send More Content]
    MODERATE --> MAINTAIN[Maintain Frequency]
    AT_RISK --> REACTIVATE[Re-engagement Campaign]
    INACTIVE --> SUNSET[Consider Sunset]

    style ACTIVE fill:#c8e6c9
    style INACTIVE fill:#ffcdd2