ShrubberyDocs
API ReferenceSign in
Guide

Teams & Org Roles

How organisations group people into Teams, who can admin what, and how that scopes the roster and commitments.

01 · Overview

Overview

Every user belongs to one organisation. Inside it, Teams group members and pin each Shrubbery to a single team_id. Roles (org_owner, team_lead, team_member) control admin powers and visibility. Commitment roles (Lead / Knight) stay on the row — they are not the same as org roles.

02 · Actors

Actors

  • Org Owner — org-wide admin: teams CRUD, role changes, ownership transfer, join-request decisions.
  • Team Lead — team-scoped leadership role on a named team (stronger than member on that team).
  • Team Member — default membership for invited users on a team.
  • Lead / Knight — still the assigner and assignee on a Shrubbery; independent of org role labels.
03 · Flow

Flow

  1. Org forms — self-serve signup creates an organisation, a default team, and grants the user Org Owner (and typically team lead on that team). Invitees join as team_member on the inviter's team path.
  2. Owner manages teams — at /org/settings the owner creates, renames, or deletes empty teams; renames the org; changes members between team_lead and team_member on a team; can transfer ownership.
  3. Owner or capture path invites — inviteUser sends a Supabase invite email; blocked if the person already belongs to another org.
  4. Outsider requests join — a signed-up user can request to join by owner email (requestToJoinOrg); owner accepts or refuses on the team surface. Accept moves organization_id and grants default-team membership (blocked if the requester still has open Shrubberies on their old org).
  5. Shrubberies land on a team — each row has a non-null team_id. If create omits it, a trigger assigns the assigner's default team. Org owners see across teams; members see their teams plus rows where they are counterparty.
04 · Edge cases

Edge cases

  • Lead ≠ Org Owner — a team member can still be Lead on commitments they assign; owner is about tenancy admin, not exclusive assigner rights.
  • One org per user — join/accept paths move the user; they do not hold concurrent orgs.
  • Delete team — only when no role rows remain; non-empty teams stay.
  • Transfer ownership — database function moves created_by and the org_owner role together so admin never orphans.
  • Join accept blocked — requester must not still own assigner/assignee rows that would break tenancy isolation; clear or complete those first.
05 · Related

Last updated: 24 July 2026