QR Code Share Token — Resolve & Add Friend Flow¶

Scope: Current iOS flow for camera scan, photo import, universal link, app deep link, and numeric call-history fallback.

flowchart TD
    classDef input fill:#EDE9FE,stroke:#7C3AED,color:#5B21B6,stroke-width:2px;
    classDef client fill:#E0F2FE,stroke:#0284C7,color:#0369A1,stroke-width:2px;
    classDef server fill:#D1FAE5,stroke:#059669,color:#047857,stroke-width:2px;
    classDef error fill:#FEE2E2,stroke:#DC2626,color:#B91C1C,stroke-width:2px;

    subgraph Inputs ["Input Sources"]
        Cam(["Camera Scan"]):::input
        Photo(["Photo Import"]):::input
        Link(["Universal Link / App Deep Link"]):::input
        History(["Call History ID"]):::input
    end

    subgraph App ["iOS Client - Contact Link Resolver"]
        Cam --> Parse["Parse scanned/imported payload"]:::client
        Photo --> Parse
        Link --> Parse
        History --> Parse

        Parse --> IsURL{"Contact link token found?"}:::client
        IsURL -->|Yes| Resolve["POST /app/api/share-token/resolve<br/>body: { token }"]:::client
        IsURL -->|No| IsNumber{"UInt64 payload?"}:::client
        IsNumber -->|Yes| ByID["POST /app/api/friend-request/by-id<br/>body: { targetUserId }"]:::client
        IsNumber -->|No| Invalid["Show invalid QR error"]:::error
    end

    subgraph Backend ["Backend"]
        Resolve --> ResolveOK["Return { token, displayName }"]:::server
        Resolve --> ResolveFail["Structured API error"]:::server
        ByID --> IDDone["Friend request sent"]:::server
    end

    ResolveOK --> Preview["Show resolved contact preview"]:::client
    Preview --> ByToken["POST /app/api/friend-request/by-token<br/>body: { token }"]:::client
    ByToken --> Done["Friend request sent"]:::client
    IDDone --> Done
    ResolveFail --> UIErr["Show localized error"]:::error