​

SPEC 012 — Team Members and Roles

​

1. Feature Purpose

​

2. Current State (Verified)

​

2.1 Backend

​

2.2 Frontend

​

3. Data Model

​

Members

​

Roles

​

MembersRoles (Join Table)

​

OrganizationsRoles (Join Table)

​

Permissions

​

PermissionsRoles (Join Table)

​

GlobalRolesUsers

​

Invitations

• invited = 1 — Email sent, awaiting action
• registered = 2 — User created an account
• joined = 3 — User accepted and joined the organization
• bounced = 4 — Email delivery failed

​

MemberLimits

​

Relationships

​

4. API Endpoints

​

Member Endpoints

​

Role Endpoints

​

Request/Response Schemas

// POST /organization/:organization/role
interface NewRoleRequest {
  organization: Uuid;
  role: string;        // role name
  description: string;
  permission: Uuid[];  // array of permission IDs
}

// PUT /organization/:organization/role/:role
interface UpdateRoleRequest {
  organization: Uuid;
  role: Uuid;
  newRole: string;      // updated role name
  description: string;
  permission: Uuid[];
}

// PUT /organization/:organization/role/:role/member
interface NewMemberRoleRequest {
  organization: Uuid;
  role: Uuid;
  member: Uuid[];  // member IDs to assign
}

// GET /organization/:organization/role/:role → response
interface Role {
  id: Uuid;
  name: string;
  description: string;
  permissions: Uuid[];
  isShared: boolean;
}

​

5. Frontend Components

​

Team Members Pages

​

Team Members Components

​

Roles Pages

​

Roles Components

​

Routes

​

Member Form Fields

interface CommonEditableMemberFields {
  title: string;
  email: string;
  roles: Uuid[];
  dateOfBirth: Date;
  address: Address;
  types: 'individual' | 'organization';
}

interface EditableMemberFields extends CommonEditableMemberFields {
  fullName: string;
  phone: string;
  user: Uuid;
}

​

6. Business Rules and Validation

​

6.1 Permissions System

• fullVoting — Full voting rights
• partialVoting — Partial voting rights
• writeSite — Write access to organization site
• readSite — Read access to organization site

​

6.2 Permission Enforcement

• canViewMember, canEditMembers, canViewMembers, canViewSomeMembers
• canViewOrganization, canEditOrganization
• canViewCapTable, canEditCapTable
• canViewDocuments, canEditDocuments, canDeleteDocuments
• And others for billing, incentive plans, signing, governing docs

​

6.3 Invitation Flow

1. Admin calls POST /organization/:organization/member/invite with member IDs
2. Server queries members by organization + IDs, deduplicates by email
3. For each unique email: creates Invitation record (status: invited), sends email via commonNotificationTemplates.organizationInvitation
4. When invitee registers: status updates to registered
5. When invitee accepts and joins: status updates to joined
6. If email bounces: status updates to bounced

​

6.4 Member Limits

​

6.5 Role Assignment Rules

• Roles are scoped to an organization via OrganizationsRoles
• Members are assigned to roles via MembersRoles (many-to-many)
• A member can have multiple roles; permissions are the union of all assigned roles’ permissions
• Roles can be shared (isShared = true) across organizations
• GlobalRolesUsers assigns platform-wide roles (admin) using integer role levels, separate from org-level RBAC

​

7. Acceptance Criteria

• Organization owner can create, edit, and delete custom roles with any combination of the 15 permissions
• Members can be assigned multiple roles; effective permissions are the union of all roles
• New members can be invited by email; invitation creates a record and sends an email notification
• Invitation status progresses through invited → registered → joined (or bounced)
• Member form captures all 9 editable fields (fullName, email, phone, title, dateOfBirth, address, user, roles, types)
• Member limit is enforced: adding members beyond the limit shows the MemberLimitError
• Permission guards on all 16 endpoints correctly deny access when the requesting user lacks the required permission
• Deleting a member removes their role assignments
• The 4 backend-only permissions (fullVoting, partialVoting, writeSite, readSite) do not appear in the frontend role editor
• Role deletion removes all PermissionsRoles and MembersRoles join records for that role

​

8. Risks and Edge Cases

​

9. Dependencies