stateDiagram-v2
    [*] --> NEW: Lead Captured

    NEW --> CONTACTED: First Contact Made
    NEW --> UNQUALIFIED: Invalid/Spam

    CONTACTED --> QUALIFIED: Meets Criteria
    CONTACTED --> NURTURING: Not Ready Yet
    CONTACTED --> UNQUALIFIED: Does Not Fit

    NURTURING --> CONTACTED: Re-engaged
    NURTURING --> UNQUALIFIED: Lost Interest

    QUALIFIED --> CONVERTED: Create Opportunity
    QUALIFIED --> UNQUALIFIED: Disqualified

    CONVERTED --> [*]
    UNQUALIFIED --> [*]

    note right of NEW
        Auto-assigned or
        in queue
    end note

    note right of QUALIFIED
        Ready for sales
        engagement
    end note

flowchart TD
    subgraph "Capture Sources"
        WEB[Website Form]
        IMPORT[CSV Import]
        API[API Integration]
        MANUAL[Manual Entry]
        SOCIAL[Social Media]
    end

    subgraph "Processing"
        RECEIVE[Receive Lead Data] --> VALIDATE[Validate Data]
        VALIDATE --> DEDUPE{Duplicate Check}
        DEDUPE -->|Exists| MERGE[Merge with Existing]
        DEDUPE -->|New| CREATE[Create Lead]

        CREATE --> ENRICH[Enrich Data]
        MERGE --> ENRICH
        ENRICH --> SCORE[Calculate Score]
        SCORE --> ASSIGN[Auto-Assign]
    end

    subgraph "Assignment"
        ASSIGN --> RULES{Assignment Rules}
        RULES -->|Round Robin| RR[Next Available Rep]
        RULES -->|Territory| TERR[Territory Owner]
        RULES -->|Skill| SKILL[Best Match Rep]
    end

    WEB --> RECEIVE
    IMPORT --> RECEIVE
    API --> RECEIVE
    MANUAL --> RECEIVE
    SOCIAL --> RECEIVE

    RR --> NOTIFY[Notify Sales Rep]
    TERR --> NOTIFY
    SKILL --> NOTIFY

    style CREATE fill:#e8f5e9

sequenceDiagram
    participant Source as Lead Source
    participant API as TRPC Router
    participant Service as Lead Service
    participant DB as Database
    participant Enrich as Enrichment Service
    participant Email as Email Service

    Source->>API: createLead(leadData)
    API->>Service: createLead(ctx, input)

    Service->>Service: Validate required fields
    Service->>DB: Check for duplicates
    DB-->>Service: Duplicate check result

    alt Duplicate found
        Service->>DB: Merge lead data
    else New lead
        Service->>DB: Create lead record
    end

    DB-->>Service: Lead created/updated

    Service->>Enrich: enrichLeadData(lead)
    Note over Enrich: Company info, social profiles
    Enrich-->>Service: Enriched data

    Service->>Service: Calculate lead score
    Service->>DB: Update lead with enrichment + score

    Service->>Service: Apply assignment rules
    Service->>DB: Assign to sales rep

    Service->>Email: notifyAssignedRep(lead)

    Service-->>API: Lead created
    API-->>Source: Success response

flowchart TD
    subgraph "Demographic Scoring"
        COMPANY[Company Size]
        INDUSTRY[Industry Fit]
        TITLE[Job Title]
        LOCATION[Location]
    end

    subgraph "Behavioral Scoring"
        PAGES[Pages Viewed]
        DOWNLOADS[Content Downloads]
        EMAIL_OPEN[Email Engagement]
        EVENTS[Event Attendance]
    end

    subgraph "Score Calculation"
        COMPANY --> DEMO_SCORE[Demographic Score: 0-50]
        INDUSTRY --> DEMO_SCORE
        TITLE --> DEMO_SCORE
        LOCATION --> DEMO_SCORE

        PAGES --> BEHAV_SCORE[Behavioral Score: 0-50]
        DOWNLOADS --> BEHAV_SCORE
        EMAIL_OPEN --> BEHAV_SCORE
        EVENTS --> BEHAV_SCORE

        DEMO_SCORE --> TOTAL[Total Score: 0-100]
        BEHAV_SCORE --> TOTAL
    end

    subgraph "Classification"
        TOTAL --> CLASS{Score Range}
        CLASS -->|80-100| HOT[Hot Lead]
        CLASS -->|50-79| WARM[Warm Lead]
        CLASS -->|20-49| COOL[Cool Lead]
        CLASS -->|0-19| COLD[Cold Lead]
    end

    style HOT fill:#c8e6c9
    style WARM fill:#fff9c4
    style COOL fill:#ffe0b2
    style COLD fill:#ffcdd2

flowchart TD
    LEAD[Lead Assigned] --> RESEARCH[Research Lead]
    RESEARCH --> CONTACT[Make Contact]

    CONTACT --> RESPONSE{Response?}
    RESPONSE -->|No Response| FOLLOWUP[Follow-up Sequence]
    RESPONSE -->|Responded| DISCOVERY[Discovery Call]

    FOLLOWUP --> ATTEMPTS{Max Attempts?}
    ATTEMPTS -->|No| CONTACT
    ATTEMPTS -->|Yes| NURTURE[Move to Nurturing]

    DISCOVERY --> BANT[BANT Qualification]

    subgraph "BANT Criteria"
        BUDGET[Budget: Can they afford?]
        AUTHORITY[Authority: Decision maker?]
        NEED[Need: Pain point exists?]
        TIMELINE[Timeline: When buying?]
    end

    BANT --> BUDGET
    BANT --> AUTHORITY
    BANT --> NEED
    BANT --> TIMELINE

    BUDGET --> EVALUATE
    AUTHORITY --> EVALUATE
    NEED --> EVALUATE
    TIMELINE --> EVALUATE

    EVALUATE{Qualified?} -->|Yes| CONVERT[Convert to Opportunity]
    EVALUATE -->|Partially| NURTURE
    EVALUATE -->|No| DISQUALIFY[Disqualify]

    style CONVERT fill:#e8f5e9
    style DISQUALIFY fill:#ffebee

sequenceDiagram
    participant Lead
    participant System as Nurturing System
    participant Email as Email Service
    participant Sales as Sales Rep

    Note over System: Lead enters nurturing

    System->>System: Add to nurture campaign

    loop Weekly for 8 weeks
        System->>Email: Send nurture email
        Email->>Lead: Educational content

        alt Lead engages
            Lead->>System: Click/Download
            System->>System: Increase score
            alt Score threshold reached
                System->>Sales: Alert: Lead re-engaged
            end
        end
    end

    Note over System: Campaign ends

    System->>System: Evaluate lead status

    alt Score improved
        System->>Sales: Move to contacted
    else No improvement
        System->>System: Archive or extend nurturing
    end

sequenceDiagram
    participant Rep as Sales Rep
    participant UI as CRM UI
    participant API as TRPC Router
    participant Service as Lead Service
    participant OppService as Opportunity Service
    participant DB as Database

    Rep->>UI: Convert lead to opportunity
    UI->>API: convertLead(leadId, opportunityData)
    API->>Service: convertLead(id, data)

    Service->>DB: Get lead details
    DB-->>Service: Lead data

    Service->>Service: Validate conversion
    Note over Service: Check: qualified status, required fields

    alt Client exists
        Service->>DB: Link to existing client
    else New client
        Service->>DB: Create client from lead
        DB-->>Service: Client created
    end

    alt Contact exists
        Service->>DB: Link to existing contact
    else New contact
        Service->>DB: Create contact from lead
        DB-->>Service: Contact created
    end

    Service->>OppService: createOpportunity(data)
    OppService->>DB: Create opportunity
    DB-->>OppService: Opportunity created

    OppService-->>Service: Opportunity

    Service->>DB: Update lead status (CONVERTED)
    Service->>DB: Link lead to opportunity

    Service-->>API: Conversion result
    API-->>UI: Success
    UI-->>Rep: View opportunity

flowchart TD
    NEW_LEAD[New Lead] --> RULES{Assignment Rules Engine}

    RULES --> CHECK1{Territory Match?}
    CHECK1 -->|Yes| TERRITORY[Assign to Territory Owner]
    CHECK1 -->|No| CHECK2

    CHECK2{Industry Specialist?}
    CHECK2 -->|Yes| SPECIALIST[Assign to Specialist]
    CHECK2 -->|No| CHECK3

    CHECK3{Lead Score > 80?}
    CHECK3 -->|Yes| SENIOR[Assign to Senior Rep]
    CHECK3 -->|No| ROUND_ROBIN

    ROUND_ROBIN[Round Robin Assignment]
    ROUND_ROBIN --> AVAILABLE{Rep Available?}
    AVAILABLE -->|Yes| ASSIGN[Assign Lead]
    AVAILABLE -->|No| QUEUE[Add to Queue]

    TERRITORY --> ASSIGN
    SPECIALIST --> ASSIGN
    SENIOR --> ASSIGN

    ASSIGN --> NOTIFY[Notify Assigned Rep]
    QUEUE --> WAIT[Wait for Assignment]

    style ASSIGN fill:#e8f5e9

gantt
    title Lead Lifecycle Example
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Capture
    Lead Created           :milestone, m1, 2024-01-01, 0d
    Auto-assigned          :milestone, m2, 2024-01-01, 0d

    section Outreach
    Email 1 Sent           :milestone, m3, 2024-01-02, 0d
    Email Opened           :milestone, m4, 2024-01-03, 0d
    Call Attempt 1         :milestone, m5, 2024-01-04, 0d
    Call Connected         :milestone, m6, 2024-01-05, 0d

    section Qualification
    Discovery Call         :disc, 2024-01-08, 1d
    Demo Scheduled         :milestone, m7, 2024-01-09, 0d
    Demo Delivered         :demo, 2024-01-12, 1d

    section Conversion
    Qualified              :milestone, m8, 2024-01-13, 0d
    Converted              :crit, milestone, m9, 2024-01-13, 0d