Linear chain structure

A linear chain is an ordered list of collaborators where every position has at most one upline (the position directly before it) and one downline (the position directly after it). It’s the simplest shape that supports a cascade, and the right pick when your org chart is a ladder rather than a tree.

How it works

Every member of a linear chain carries an integer position in their metadata. Lower numbers sit closer to the top. Position 1 is the head of the chain. Position N is the tail.

Positions don’t have to be perfectly contiguous, but the natural shape (and what the admin UI produces) is 1, 2, 3, … with no gaps and no duplicates. Treat positions as a strict order, not as a score. Layers are counted by rank in that order, not by the numeric gap between positions, so positions 1, 5, 9 behave exactly like 1, 2, 3 and yield layers 1, 2, 3.

From any member’s point of view, upline means walking toward lower positions, so the person at position 4 has position 3 as their layer-1 upline, then position 2 as layer 2, then position 1 as layer 3. Downline runs the other way, toward higher positions, so position 4 has position 5 as their layer-1 downline, position 6 as layer 2, and so on. Either direction is measured in layers, the 1-indexed distance from the triggering collaborator, where layer 1 is the immediate neighbor.

The head of the chain has no upline. The tail has no downline. Cascades simply stop when they run out of chain.

In the admin UI you don’t type positions by hand. You drag members into the order you want and Siren recomputes positions on save based on the visual order. Add a new member at the bottom and they take the next position. Remove someone from the middle and the positions below shift up so the chain stays contiguous.

Inactive members, suspended or deleted, earn nothing and are skipped, but they do not renumber the layers around them. A member’s layer is fixed by their position in the chain, not by how many members happen to be active. If the layer-2 upline is suspended, layer 2 pays no one and the person above them stays at layer 3, credited at the layer-3 score. The cascade keeps walking up the chain past the skipped member and stops only when a layer is set to 0 or the chain runs out.

When to use it

Pick a linear chain when your structure is fundamentally ordered and one-dimensional. The quickest way to check is to ask “who’s above this person?” If you can answer with a single name rather than a list, a chain fits. A simple sales-team ladder is the classic case, where rank determines override depth: the newest rep sits at the tail, the regional director at the head, and every sale pays the people above the seller. The same shape covers a single reporting line where a rep rolls up to a manager who rolls up to a director, since that’s naturally a chain rather than a tree, as well as a partner chain for tiered programs where each partner sits beneath the one above them, in order.

If your structure branches (one person has multiple direct reports, or one manager has many direct reports), you want parent-child instead. Parent-child encodes a tree, which a linear chain can’t represent.

If you don’t need a hierarchy at all and every member should be treated equally, see the choosing a collaborator group structure overview for when flat is the right call.

A linear chain pairs naturally with the upline cascade and downline cascade calc strategies. Upline cascade walks toward the head when someone makes a sale and pays the people above them. Downline cascade walks toward the tail.

Configuration

In the admin UI:

1. Create a CollaboratorGroup or open an existing one. See create a collaborator group for the full walkthrough.
2. Set the structure to Linear Chain.
3. Add members.
4. Drag them into the order you want. Top of the list becomes position 1.
5. Save. Siren writes the positions based on the visual order.

In the API, PUT to /collaborator-groups/{id}/members with each member carrying metadata.position as an integer:

{
  "members": [
    { "collaboratorId": 101, "metadata": { "position": 1 } },
    { "collaboratorId": 102, "metadata": { "position": 2 } },
    { "collaboratorId": 103, "metadata": { "position": 3 } }
  ]
}

This PUT replaces the group’s full member list. Any member not included in the body is removed from the group, so send every member you want to keep. To add or remove individual members without replacing the list, use the add and remove member endpoints instead.

Lower position values sit closer to the head of the chain. The triggering collaborator is never credited by the cascade itself, only the layers above or below them, depending on which calc strategy is bound.

A member whose position is missing or non-numeric is read as position 0, which sorts to the top of the chain. Members that share a position keep their existing order, so a group switched to linear chain from another structure starts with every member at position 0, in their current order, until you set real positions. Set positions before any cascade fires, because while members are tied at 0 the chain order is just the order they already had, and overrides would pay out along that incidental order rather than the hierarchy you intend. Every member stays part of the group regardless of position, so a member left at 0 is still in the chain. They just sit at the head until you give them an order.