← Technical notes

Illustrative

Based on patterns I've built in production (details under NDA). The example domain below is illustrative.

Multi-level revenue splits with a dry-run preview

Example domain: a brand sells through distributors, dealers and retailers. Each level keeps the difference between its rate and the rate of the level below it.

The problem

Fee rules changed from one flat rate to percent + fixed, split down a chain of levels. Ops needed to change rates safely, without surprises in real payouts.

How it works

  1. Walk the chain from the top rate downward. Each level's own rate is clamped between 0 and the level above; the level earns the difference.
  2. A missing or inactive level earns nothing and does not shift its gap to others.
  3. Percent and fixed parts are split the same way; money is computed cumulatively and rounded once per level, so rounding never overpays.
  4. Whatever is left belongs to the platform; negative leftovers are clamped to zero.
  5. Preview runs the same split function with draft rates and returns every level's share without writing anything.
  6. Settle only runs if the transaction is still in a settle-able state (a guarded update), then inserts split rows backed by a unique constraint, so a duplicate settle is rejected.

Migration approach

Added percent and fixed columns beside the legacy rate columns, backfilled old rows into one part, dual-wrote both during transition, and never recalculated already-settled records.

Loading diagrams…