Invite Tree Module

Location: apps/api/src/modules/invite-tree/

Aggregate root: InviteNode

Purpose: Records who invited whom as a materialized tree, so the platform can show lineage ("who you brought in", ancestors/descendants) and let cross-cutting concerns (contribution, reputation) inherit value along the invite chain. Reading-only domain — nodes are written reactively, never by a direct client mutation.

---

Model

InviteNode stores an ltree-style path (dotted ancestor ids) plus a denormalized depth, so an entire subtree is a single path startsWith "<userId>." scan and a depth-ordered traversal needs no recursion.

Field	Meaning
userId	The invited user (one node per user)
inviterUserId	Direct inviter (null for the seed/root)
path	Dotted ancestor chain, e.g. root.alice.bob
depth	Distance from the root
createdAt	When the node was created (ISO-serialized in responses)

How nodes are created

The module subscribes to identity.user.registered (UserRegisteredEvent) and inserts the new user's node under their inviter — there is no write endpoint. This keeps the tree consistent with registration without a cross-context service call.

Endpoints (read-only, all /invite-tree/me…)

Method	Path	Purpose
GET	/invite-tree/me	The caller's own node
GET	/invite-tree/me/ancestors	Chain up to the root
GET	/invite-tree/me/children	Direct invitees (raw nodes)
GET	/invite-tree/me/invitees	Direct invitees enriched with profile data
GET	/invite-tree/me/descendants	Whole subtree, depth-then-time ordered, enriched

The enriched queries (invitees, descendants, ancestors) batch-load profile data with a single IN-query and ISO-serialize createdAt so the client contract is a string, consistent with every other serializer.

Related

• Allocation: the number of invite codes a user gets is reputation-based (see Identity), not a flat cap.
• Inheritance: Contribution walks the tree so an invitee's activity credits their inviter chain.

See also: /modules/identity, /modules/contribution