sequenceDiagram
    participant User
    participant Proxy
    participant Browser
    participant AttributionAPI
    participant RedeemAPI
    participant BonusCredits
    participant DB

    Note over User,DB: UTM-Based Attribution Flow
    User->>Proxy: Visit auth page with UTM params
    Proxy->>Browser: Set sim_utm cookie (UTM data + timestamp)
    Browser->>Proxy: Complete signup
    User->>Browser: Navigate to workspace page
    Browser->>AttributionAPI: POST /api/attribution (with cookie)
    AttributionAPI->>DB: Check user created_at vs cookie timestamp
    AttributionAPI->>DB: Find matching campaign by UTM specificity
    AttributionAPI->>DB: Begin transaction
    AttributionAPI->>DB: Ensure userStats exists
    AttributionAPI->>DB: Insert referral_attribution (conflict: userId)
    alt Attribution successful
        AttributionAPI->>BonusCredits: applyBonusCredits(userId, amount, tx)
        BonusCredits->>DB: Get subscription plan
        alt Team/Enterprise
            BonusCredits->>DB: Update org.creditBalance + orgUsageLimit
        else Free/Pro
            BonusCredits->>DB: Update userStats.creditBalance + currentUsageLimit
        end
        AttributionAPI->>DB: Commit transaction
        AttributionAPI->>Browser: { attributed: true, bonusAmount }
    else Already attributed
        AttributionAPI->>DB: Rollback (conflict)
        AttributionAPI->>Browser: { attributed: false }
    end

    Note over User,DB: Manual Code Redemption Flow
    User->>Browser: Enter referral code in settings
    Browser->>RedeemAPI: POST /api/referral-code/redeem { code }
    RedeemAPI->>DB: Get user subscription plan
    alt Enterprise user
        RedeemAPI->>Browser: { error: "Enterprise cannot redeem" }
    else Non-enterprise
        RedeemAPI->>DB: Find campaign by code
        RedeemAPI->>DB: Check existing user attribution
        RedeemAPI->>DB: Check existing org attribution (if team)
        alt Code available
            RedeemAPI->>DB: Begin transaction
            RedeemAPI->>DB: Ensure userStats exists
            RedeemAPI->>DB: Insert referral_attribution (with orgId if team)
            RedeemAPI->>BonusCredits: applyBonusCredits(userId, amount, tx)
            BonusCredits->>DB: Update credit balance based on plan
            RedeemAPI->>DB: Commit transaction
            RedeemAPI->>Browser: { redeemed: true, bonusAmount }
        else Already redeemed
            RedeemAPI->>Browser: { error: "Already redeemed" }
        end
    end