Org Hierarchy & Permissions

How to model accounts, teams, roles, content ownership, and shared resources.

01The Org Hierarchy

An account is the billing and tenancy root — one per customer. Below it, any number of nested nodes representing teams, offices, regions, or divisions.

The full tree lives on a single account document. Node IDs are org IDs — existing orgId foreign keys across the product don't change.

What the account document looks like

{
  "id": "acct-jll",
  "name": "JLL",
  "rootNodeId": "acct-jll",
  "nodes": {
    "acct-jll":    { type: "account", parentId: null,       childIds: ["denver","nyc","sf"] },
    "denver":      { type: "team",    parentId: "acct-jll", childIds: ["denver-is","denver-mtg"] },
    "denver-is":   { type: "team",    parentId: "denver",   childIds: [] },
    "denver-mtg":  { type: "team",    parentId: "denver",   childIds: [] },
    "nyc":         { type: "team",    parentId: "acct-jll", childIds: ["nyc-is"] },
    "nyc-is":      { type: "team",    parentId: "nyc",      childIds: [] },
    "sf":          { type: "team",    parentId: "acct-jll", childIds: [] }
  }
}

Every customer shape is just a tree depth

Structural operations — cheap metadata edits

02Users, Roles & Auth

Users belong to an account via accountId. Canonical role assignments live on user documents, keyed by node ID.

The cast

// Sarah — corporate admin for all of JLL
{ accountId: "acct-jll",  roleAssignments: { "acct-jll": ["account_admin"] } }

// Mike — Denver regional manager
{ accountId: "acct-jll",  roleAssignments: { "denver": ["admin"] } }

// Lisa — Denver IS analyst
{ accountId: "acct-jll",  roleAssignments: { "denver-is": ["user"] } }

// Tom — cross-branch: viewer on Denver, user on SF
{ accountId: "acct-jll",  roleAssignments: { "denver": ["viewer"], "sf": ["user"] } }

Role definitions

Roles are global constants. Each maps to a flat array of action verbs.

As we add products, we add action verbs (deal:read, underwriting:write). The schema shape doesn't change.

Auth algorithm

Walk from the target node to the root. At each stop, check if the user has a role. Union all matched action arrays. Allow if the requested action is present.

function can(user, action, targetOrgId, accountTree) {
  const path = getPathToRoot(accountTree, targetOrgId);
  for (const nodeId of path) {
    for (const role of user.roleAssignments[nodeId] ?? []) {
      if (roleDefinitions[role].includes(action)) return true;
    }
  }
  return false;
}

Cost: two reads — the user doc and the account doc. Both are already hot in every request. No per-artifact ACL lookup.

Authorization examples

03Content Keying & List Queries

Artifacts live on nodes

Both leaf and non-leaf nodes can own content. For ex, if an artifact naturally belongs to the Denver region (not specifically IS or MTG), it lives there.

Deriving the accessible list for each user

Start from the user's role assignments. Expand each downward through all descendants. Collect the full set of accessible node IDs. Fan out the query.

What each user sees — concrete results

Note that Mike cannot see the corporate overview — it lives on acct-jll and Mike only has a role on denver. Tom can see Denver-branch decks but only as read-only (viewer), while he can read/write in SF.

Workspace switcher UX

• Users with access to multiple nodes get a switcher.
• The active context determines where new artifacts are created.
• Admins can toggle between "just this team" (filter by active node) and "everything I can see" (fan out across all accessible nodes).
• The query shape remains the same — only the input set of node IDs changes.

Why not account-scoped artifacts?

The alternative: store all artifacts at the account level and filter by permissions.

The indirection is unavoidable

Without per-artifact ACLs or per-user artifact lists, something has to mediate access. There are two options:

• Group users, attach access state to each artifact — ACLs, sharing lists, tags.
• Group artifacts by owning node, attach permissions to users on those nodes.

Account-scoping doesn't remove this choice. It defaults to option 1, where the complexity scales with artifact count instead of being handled once in the org structure.

04Library Assets & Config

• Artifacts are created at the team level — a deck belongs to the team that made it. Access comes from above: a Denver admin sees Denver IS decks because their role inherits down to where the content lives.
• Library assets work the other way around — a corporate color palette or regional boilerplate slides are defined higher up and published downward to the teams that need them.
  • Because they flow in opposite directions, library assets need their own visibility model — decoupling "who can use this resource" from "who can access this node's content."

Ownership vs. Visibility

Each library asset has:

• orgId — who owns it (and can edit it)
• visibility — who can use it: local, descendants, or account

Publishing more broadly changes availability, not ownership. Three levels keep it simple — no need for arbitrary sharing lists.

Library visibility examples

Resolving available library assets

Why library assets can't just be artifacts

Config Resolution

Configuration lives on org node documents. Resolution: read the key on the current node. If missing, walk up to the root.

Config examples

The org-hierarchy tree is the single organizing principle