LeadFlow PM

A complete lead marketplace with transparent commission settlement.
3 active roles: Channel Partner · Sales Member · Admin (IdealWarren)

Core Flow — Registration to Commission

1.1 Channel Partner Onboarding

CP Registers
Signs up at CP Portal
→ status: pending
Admin Approves
Reviews documents
→ status: active
CP Sets Profile
Bank details, documents
ready to submit leads
Example

Originator (CP A) — Sarah from "Acme Realty" registers. Admin Mike approves. She uploads price list & bank details.

Allocated (CP B) — David from "Best Homes" also registers and gets approved. Ready to receive leads.

1.2 Lead Submission & Allocation

Originator (CP A)
Submits Lead
e.g. "Luxury Villa — Mayfair"
£10,000 · currency: GBP
Admin Allocates
Assigns lead
to Allocated (CP B)
Allocated (CP B)
Receives Lead
Appears in their Kanban
ready to work
Example

Sarah (Originator) submits "Luxury Villa — Mayfair" worth £10,000. Mike allocates it to David (Allocated CP B). David sees it in his Kanban at stage New.

1.3 Kanban Progression → Won Triggers Commission

New
Contacted
Negotiation
WON
→ CommissionTransaction
is auto-created
📥 New
📞 Contacted
🤝 Negotiation
🏆 Won
❌ Lost

Commission Breakdown — Admin Panel View

Once a lead is won and the Admin approves the commission, this is what the Admin sees:

Commission £110.00
← approved by admin
Platform fee
[% of commission] [Fixed] − £10.00
admin picks Fixed, enters 10 → calls handleApplyPlatformFee
→ api.updateLead({feeOverrideType:'fixed', feeOverrideValue:10})
→ backend recomputes platformFee + net + originatorFee
Net £100.00
Originator fee
[% of net] [Fixed] − £30.00
admin picks Fixed, enters 30 → calls handleSetOriginatorFee
→ POST /leads/:id/originator-fee
→ recomputes originatorFeeAmount only
Admin revenue £70.00
← net − originator fee (admin keeps this)
🔢 Math trace (computeCommissionMath in leads.service.ts):
commissionAmount = 110
feeOverrideType='fixed', feeOverrideValue=10 → platformFee = 10 (fixed branch)
netCommission = 110 − 10 = 100
originatorFeeType='fixed', originatorFeeValue=30 → originatorFeeAmount = 30 (fixed branch)
adminRevenue = net − originatorFee = 100 − 30 = 70
💰 Who gets what:
• Platform fee (£10) → Admin must settle this to the Platform (via PlatformFeeSettlement)
• Originator fee (£30) → Admin pays to Originator (CP A)
• Admin revenue (£70) → Admin retains this

Commission Approval & Locking Flow

1. Allocated (CP B)
Proposes commission
e.g. £110
2. Admin Approves
Can override amount
Recomputes all math
3. Set Originator Fee
% of net or Fixed
→ CP A's payout
4. Amend & LOCK
One-shot final change
ALL FIELDS FROZEN
🔒 Lock behavior: After Amend & Lock, commissionLocked = true. Platform fee editor and originator fee editor switch to display-only with "— locked". No further changes allowed — gross, platform fee, net, and originator fee are all frozen.
✏️ Pre-lock flexibility: Admin can update the platform fee after approval — update() re-runs the math when feeOverrideType/Value changes and re-derives both netCommission and originatorFeeAmount. Changing the originator fee only recomputes originatorFeeAmount (commission + platform fee untouched).

Payment Cycle — Post-Lock Settlement

Allocated (CP B)
Pays gross £110
to Admin's bank
Admin Marks Paid
Uploads bank receipt
Status → paid
Originator (CP A)
Admin settles originator
Pays £30 + uploads slip
Platform Fee Settlement
Admin settles £10
to the Platform

Allocated (CP B)

Pays £110 gross commission. No visibility into the split. Their job is done.

Originator (CP A)

Receives £30 originator payout. Never sees gross (£110), platform fee (£10), or net (£100). The maskForOriginator helper strips those fields.

Admin (IdealWarren)

Revenue = £70 (net − originator). Shown as "Admin Net" column. Responsible for settling platform fee to the Platform.

Platform

Receives the full platform fee = £10. Admin settles this via PlatformFeeSettlement (bulk).

💡 For IWFMS-originated leads (no CP A): The originator fee block doesn't render. Admin revenue = Net (£100 in this example).

Sales Team — CP-Owned & IWFMS-Owned

5.1 CP-Owned Sales Member

CP Creates SM
From Sales Team page
parentType: cp
SM Logs In
Same portal (:3000)
Limited sidebar
SM Submits Lead
Originated by SM
Parent CP gets credit
Commission Base
originatorPayoutAmount
(CP A's slice)

5.2 IWFMS-Owned Sales Member

Admin Creates SM
At :3001
parentType: platform
SM Logs In
Same portal (:3000)
"IWFMS Sales" branded
SM Submits Lead
Originated by SM
No parent CP
Commission Base
netCommission
(Admin's pool)

CP-Owned SM Fee Base

commissionTx.originatorPayoutAmount — the CP A slice from Admin. CP sets fee & pays.

IWFMS-Owned SM Fee Base

commissionTx.netCommission — Admin's pool after platform fee. Admin sets fee & pays.

Platform Fee Settlement — Admin Pays the Platform

Fees Accumulate
Per won lead
platform fee is calculated
Admin Bulk Settles
Selects transactions
→ PlatformFeeSettlement
Platform Receives
Full platform fee
+ bank slip uploaded
Example

Admin Mike has 3 won leads with platform fees: £10 + £25 + £15 = £50 total. He creates a PlatformFeeSettlement, pays £50 to the Platform's bank account, uploads the receipt → completed.

The Platform receives the full platform fee — no split, no deduction.

💰 Platform Fee Rule: Admin owes the full platform fee to the Platform. Admin settles these in bulk via the Platform Fee Settlement page at :3001. The Platform receives 100% of the platform fee amount.

Stakeholder Summary

RolePortalActionReceives / Sees
Originator (CP A) :3000 Submits leads Receives originator fee. Only sees originatorPayoutAmount — never gross, platform fee, or net.
Allocated (CP B) :3000 Works leads, proposes commission, pays gross Sees gross commission & status. No visibility into platform fee or originator split.
Sales Member :3000 (limited sidebar) Submits leads for parent (CP or IWFMS) Sees lead list — hides allocated CP name & lead value. Shows Pending/Allocated pill.
Admin (IdealWarren) :3001 Approves CPs, allocates leads, approves commissions, settles platform fees Keeps admin revenue (net − originator). Full transparency on all fields.
Platform :3002 (Super Admin) Configures platform fee rate, monitors Receives full platform fee from Admin via PlatformFeeSettlement.

✅ Complete LeadFlow Commission Engine

Propose → Approve → Platform Fee → Originator Fee → Amend & Lock → Payment → Settlement

Originator (CP A) only sees originator payout · Admin settles full platform fee to Platform · All flows locked after amend

LeadFlow PM v2.0 · IdealWarren