flowchart TD
WH["Webhook Received\nPOST /api/leads/incoming"] --> VAL["Validate & Dedupe"]
VAL --> INSERT["Insert Lead (pending)"]
INSERT --> ASSIGN["Assignment Engine\n(SQL RPC + Global Lock)"]
ASSIGN -- "Match Found" --> ASSIGNED["Lead Assigned to Broker\nOrder Updated"]
ASSIGN -- "No Match" --> UNASSIGNED["Unassigned Queue\n(with reason)"]
ASSIGNED --> HOURS{"Within Broker\nContact Hours?"}
HOURS -- "Yes" --> DELIVER["Fire Delivery"]
HOURS -- "No" --> QUEUED["Queue for Later"]
QUEUED -- "Cron */5 min" --> HOURS
DELIVER --> CRM["CRM Webhook\n(pg_net)"]
DELIVER --> EMAIL["Email\n(GHL)"]
DELIVER --> SMS["SMS\n(GHL)"]
CRM & EMAIL & SMS -- "Success" --> SENT["Delivered ✅"]
CRM & EMAIL & SMS -- "Failed" --> RETRY{"Retries < 3?"}
RETRY -- "Yes" --> DELIVER
RETRY -- "No" --> FAILED["Permanent Failure ❌\nAdmin Alerted"]
SENT & FAILED & UNASSIGNED -.-> DASH["Admin Dashboard\nKPIs · Activity · Management"]
classDef success fill:#10b981,stroke:#059669,color:#fff
classDef fail fill:#ef4444,stroke:#dc2626,color:#fff
classDef info fill:#3b82f6,stroke:#2563eb,color:#fff
class SENT success
class FAILED fail
class WH info
Created
March 13, 2026 14:26
-
-
Save hmseeb/d48838353bb72529325c5750c4e1baad to your computer and use it in GitHub Desktop.
PPL Leadr Management — High-Level System Flow (Mermaid)
Author
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
The assignment engine looks for an active order that fits the incoming lead. A "match" means it found one where:
If multiple orders qualify, it picks the one with the most remaining capacity relative to total, breaking ties by whoever was assigned longest ago (round-robin fairness).
No match = lead goes to the unassigned queue with a reason why.