sequenceDiagram
    participant Client
    participant Worker as Cloudflare Worker
    participant DB as D1 Database
    participant DNS as DNS API
    
    Client->>Worker: POST /validate {email}
    Worker->>DB: Check API Key
    
    alt Invalid Key
        Worker-->>Client: 401 Unauthorized
    else Valid Key
        Worker->>DB: Check Cache
        
        alt Cache Hit
            DB-->>Worker: Cached Result
            Worker-->>Client: Return Result (fast)
        else Cache Miss
            Worker->>Worker: Validate Syntax
            Worker->>DNS: Query A & MX Records
            DNS-->>Worker: DNS Results
            Worker->>DB: Check Banned Domains
            DB-->>Worker: Domain Status
            Worker->>DB: Store Result
            Worker-->>Client: Return Validation Result
        end
    end
                    

flowchart TD
    Start([Email Validation Request]) --> CheckCache{Check Cache}
    CheckCache -->|Cached as Spam| ReturnSpam[Return: is_spam=true]
    CheckCache -->|Cached as Good| ReturnGood[Return: Cached Valid Result]
    CheckCache -->|Not Cached| SyntaxCheck{Valid Email Syntax?}
    
    SyntaxCheck -->|No| Invalid[Return: invalid=true]
    SyntaxCheck -->|Yes| ExtractDomain[Extract Domain]
    
    ExtractDomain --> CheckBanned{Domain in Banned List?}
    CheckBanned -->|Yes| ReturnDisposable[Return: disposable=true]
    CheckBanned -->|No| CheckARecord{Domain Has A Record?}
    
    CheckARecord -->|No| NoARecord[Return: domain_exists=false]
    CheckARecord -->|Yes| CheckMX{Has MX Records?}
    
    CheckMX -->|No| NoMX[Return: has_mx_records=false]
    CheckMX -->|Yes| CheckRole{Role Account?}
    
    CheckRole -->|Yes| MarkRole[Set is_role_account=true]
    CheckRole -->|No| CheckFree{Free Email Provider?}
    
    MarkRole --> CheckFree
    CheckFree -->|Yes| MarkFree[Set is_free_email=true]
    CheckFree -->|No| AllValid
    
    MarkFree --> AllValid[All Checks Passed]
    AllValid --> CacheResult[Cache Result in DB]
    CacheResult --> ReturnValid[Return: valid=true]
    
    ReturnSpam --> End([End])
    ReturnGood --> End
    Invalid --> End
    ReturnDisposable --> End
    NoARecord --> End
    NoMX --> End
    ReturnValid --> End
    
    style Start fill:#667eea,stroke:#764ba2,stroke-width:3px,color:#fff
    style End fill:#667eea,stroke:#764ba2,stroke-width:3px,color:#fff
    style ReturnValid fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style ReturnSpam fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style Invalid fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style ReturnDisposable fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
                    

stateDiagram-v2
    [*] --> Uncached: New Email
    
    Uncached --> Validated: Validation Request
    Validated --> CachedValid: Valid Result + Cache
    Validated --> CachedInvalid: Invalid Result + Cache
    
    CachedValid --> MarkedGood: /mark-good endpoint
    CachedInvalid --> MarkedSpam: /mark-spam endpoint
    CachedValid --> MarkedSpam: Email bounces
    
    MarkedGood --> CachedValid: Positive feedback
    MarkedSpam --> PermanentSpam: Permanent Cache
    
    PermanentSpam --> [*]: Never Re-validated
    
    CachedValid --> Validated: Cache Refresh
    CachedInvalid --> Validated: Cache Refresh
    
    note right of PermanentSpam
        Spam emails are permanently
        cached and never re-validated
        to optimize performance
    end note
    
    note right of MarkedGood
        Good emails are cached
        with positive validation
        results for faster lookups
    end note
                    

graph TB
    subgraph "Client Layer"
        Client[Client Application]
    end
    
    subgraph "Cloudflare Workers Edge"
        Worker[BounceZero Worker]
        AuthModule[Authentication Module]
        ValidationEngine[Validation Engine]
        CacheModule[Cache Manager]
        DomainModule[Domain Manager]
    end
    
    subgraph "Data Layer"
        D1[(D1 Database
SQLite)]
        DNSAPI[Cloudflare DNS API
DNS over HTTPS]
    end
    
    subgraph "CI/CD Pipeline"
        GitHub[GitHub Actions]
        Deploy[Wrangler Deploy]
        BlocklistSync[Blocklist Sync Job]
    end
    
    Client -->|HTTPS Request| Worker
    Worker --> AuthModule
    AuthModule -->|Verify Key| D1
    Worker --> ValidationEngine
    ValidationEngine --> CacheModule
    CacheModule -->|Read/Write| D1
    ValidationEngine -->|DNS Queries| DNSAPI
    ValidationEngine --> DomainModule
    DomainModule -->|Check Banned| D1
    
    GitHub -->|Push to Main| Deploy
    Deploy -->|Deploy Code| Worker
    GitHub -->|Scheduled| BlocklistSync
    BlocklistSync -->|Update| D1
    
    style Worker fill:#667eea,stroke:#764ba2,stroke-width:3px,color:#fff
    style D1 fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style DNSAPI fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
    style GitHub fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#000