Designing an agent tree that survives ten tiers deep

Most agent networks start life in a spreadsheet, one tab per tier, reconciled by hand at the end of the week. It works until a branch grows a branch of its own, at which point the columns stop describing the shape of the business.

The failure is not arithmetic, it is structure. A hierarchy has parents, depth and inheritance; a grid has none of those, so every question about a sub-branch becomes a manual lookup.

Give every account a parent and a depth, and the hierarchy becomes queryable. A path column (the chain of ancestor ids, stored alongside the row) turns “everything under this agent” into a prefix match rather than a recursive walk at request time.

Depth is worth storing explicitly even though it is derivable. Commission schedules, limits and permissions are all defined per tier, and reading the tier should not require climbing the tree.

Commission accrues on settled rounds, not on API calls. When a round settles, the ancestor chain is already on the account, so each tier's share can be written as its own ledger entry in one pass: no traversal, no nightly job that has to be rerun when it fails halfway.

Writing each tier's share as a real entry rather than deriving it on demand also means a rate change applies from the day it was made, and history stays true to the schedule in force at the time.

A limit granted at one tier is a claim on the tier above it. The rule that keeps a tree solvent is simple to state and easy to omit: no branch can extend more credit than remains unallocated from its own limit.

Enforced at issue time, that keeps exposure bounded by the top of the tree. Enforced only in reporting, it produces a network that looks healthy until the week it doesn't.

Settlement runs along edges, not across the whole network: each agent settles with their direct parent. A ten-tier tree therefore settles in ten local conversations rather than one global reconciliation, and a stalled branch is contained to the edge it sits on.

Freezing has to work the same way. Suspending an agent suspends the subtree beneath them, because their liability is what stood behind it.

Three things, reliably: reports that were written assuming two tiers, permission checks that walk the tree per request, and commission schedules with no rule for what happens when a tier is removed. All three are cheap to handle in the model and expensive to retrofit.

Reparenting is the one worth deciding early. When an agent leaves, their subtree has to attach somewhere, and whether historic commission follows it is a commercial answer the data model has to be able to express.