Designing agent hierarchies that don't collapse under commission disputes

Every POS and VTU platform we've rebuilt had the same root problem: the agent hierarchy was modeled as a convenience for the dashboard, not as a source of truth for money. That gap is where commission disputes are born.

Model the tree, not the table

A flat "agent" table with a parent_id column looks fine until you need to answer "what did this sub-agent's whole downline earn this month." Treat the hierarchy as a first-class structure with its own audit log, not a foreign key you join against at query time.

The dashboard should never calculate a commission on the fly. If it can be recalculated, it can be disputed.

Snapshot commission rates at the transaction, not the agent

Rates change. If you store "current rate" on the agent record and back-calculate historical commissions from it, every rate change silently rewrites history. Snapshot the rate that applied at the moment of the transaction, every time.

Settlement is a separate state machine from the sale

A sale being successful and a commission being settled are two different events with two different failure modes. Keeping them as one status field is the single most common cause of "why does this agent's balance not match support's records" tickets.

None of this is exotic engineering — it's just modeling the business correctly from day one, which is the same principle behind every build in our POS & VTU services.