Teams & Sub-Groups

Group members of an Organization into named Teams — each with their own LEAD role that acts as a scoped "mini admin". Teams enable Malet Owners to partition their staff by function (e.g. Engineering, Marketing, Kitchen) while maintaining clear access control boundaries. For fine-grained permission assignment beyond base roles, see Custom RBAC.

Architecture Overview

Teams are fully contained within the organizations subgraph. The Team entity groups members, while the TeamMembership join collection tracks which users belong to which teams and in what role.

Authorization Model

Teams use a dual-check authorization pattern — certain operations require either org-level admin permissions OR team-level LEAD status:

┌──────────────────────────────────────────────────────────────┐
│                    Org Admin (OWNER/ADMIN)                    │
│                                                              │
│  ✅ createTeam    ✅ deleteTeam    ✅ updateTeamMemberRole    │
│  ✅ updateTeam    ✅ addTeamMember ✅ removeTeamMember        │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                     Team LEAD (scoped)                        │
│                                                              │
│  ❌ createTeam    ❌ deleteTeam    ❌ updateTeamMemberRole    │
│  ✅ updateTeam    ✅ addTeamMember ✅ removeTeamMember        │
│          (own team only)                                     │
└──────────────────────────────────────────────────────────────┘

• Org Admin Only: Create teams, delete teams, promote members to LEAD
• Org Admin OR Team LEAD: Update team info, add/remove members within the team

Entity Schema

Team

Indexes:

• { organizationId: 1 } — Fast org-level team lookups
• { organizationId: 1, slug: 1 } — Unique slug per organization

TeamMembership

Indexes:

• { teamId: 1, userId: 1 } — Unique constraint: one membership per user per team
• { organizationId: 1, userId: 1 } — Fast "which teams is this user in?" queries

GraphQL Mutations

Create Team (Org Admin Only)

Create a new team within an Organization. Requires MANAGE_TEAMS permission.

mutation CreateTeam($input: CreateTeamInput!) {
	createTeam(input: $input) {
		id
		name
		slug
		organizationId
		memberCount
		maletIds
	}
}

Variables:

{
	"input": {
		"orgId": "org-abc123",
		"name": "Kitchen Staff",
		"description": "Handles all food preparation",
		"slug": "kitchen-staff",
		"maletIds": ["malet-cafe-01"]
	}
}

slug is optional — if omitted, an 8-character alphanumeric slug is auto-generated. Must be unique within the organization.

Update Team (Org Admin OR Team LEAD)

mutation UpdateTeam($input: UpdateTeamInput!) {
	updateTeam(input: $input) {
		id
		name
		description
		maletIds
	}
}

Variables:

{
	"input": {
		"teamId": "team-xyz789",
		"name": "Kitchen & Bakery",
		"description": "Updated scope to include bakery operations",
		"maletIds": ["malet-cafe-01", "malet-bakery-02"]
	}
}

Delete Team (Org Admin Only)

Deletes a team and cascades all team memberships. Requires both orgId and teamId.

mutation DeleteTeam($orgId: ID!, $teamId: ID!) {
	deleteTeam(orgId: $orgId, teamId: $teamId) {
		id
		name
	}
}

Add Team Member (Org Admin OR Team LEAD)

Add an existing Organization member to a team. The user must already be a member of the Organization — this is validated server-side.

mutation AddTeamMember($input: AddTeamMemberInput!) {
	addTeamMember(input: $input) {
		id
		memberCount
	}
}

Variables:

{
	"input": {
		"teamId": "team-xyz789",
		"userId": "user-staff-001",
		"role": "MEMBER"
	}
}

The role field is optional and defaults to MEMBER. Only Org Admins can set role: "LEAD" via the updateTeamMemberRole mutation.

Remove Team Member (Org Admin OR Team LEAD)

mutation RemoveTeamMember($input: RemoveTeamMemberInput!) {
	removeTeamMember(input: $input) {
		id
		memberCount
	}
}

Update Team Member Role (Org Admin Only)

Promote or demote a team member between LEAD and MEMBER. Team LEADs cannot promote others — this is an org-admin-only operation to prevent privilege escalation.

mutation UpdateTeamMemberRole($input: UpdateTeamMemberRoleInput!) {
	updateTeamMemberRole(input: $input) {
		id
		userId
		role
	}
}

Variables:

{
	"input": {
		"orgId": "org-abc123",
		"teamId": "team-xyz789",
		"userId": "user-staff-001",
		"role": "LEAD"
	}
}

GraphQL Queries

List Organization Teams

Returns all teams within an organization, sorted alphabetically.

query OrganizationTeams($orgId: ID!) {
	organizationTeams(orgId: $orgId) {
		id
		name
		slug
		description
		memberCount
		maletIds
		createdBy
		createdAt
	}
}

Get Single Team

query Team($teamId: ID!) {
	team(teamId: $teamId) {
		id
		name
		description
		memberCount
		maletIds
	}
}

List Team Members

query TeamMembers($teamId: ID!) {
	teamMembers(teamId: $teamId) {
		id
		userId
		role
		joinedAt
	}
}

My Teams

Get the current user's teams within an organization — useful for rendering team badges or filtering content by team context.

query MyTeams($orgId: ID!) {
	myTeams(orgId: $orgId) {
		id
		name
		slug
		memberCount
	}
}

Audit Events

All team operations are logged to the Organization Audit Trail and visible via the existing organizationAuditEvents query.

Permission Matrix

The MANAGE_TEAMS permission is automatically granted to Organization OWNER and ADMIN roles via BASE_ROLE_PERMISSIONS. Members and Viewers do not have team management access.

Malet Scoping (Forward-Thinking)

The maletIds field on Team establishes a data-model link between teams and the Malets they manage. This is not enforced in access control today — it's queryable metadata.

With the Custom RBAC system now live:

1. The maletIds field becomes the enforcement bridge
2. Guards can check: "Is this user's team assigned to this Malet?"
3. No schema changes needed — the field simply starts being checked

This design allows Malet Owners to assign specific teams to specific Malets now (e.g., "The Kitchen Staff team manages Café Malet"), with cross-subgraph enforcement being the next step.

Module Structure

apps/organizations/src/team/
├── team.types.ts                 # TeamRole enum (LEAD, MEMBER)
├── team.entity.ts                # Team entity (Typegoose + GraphQL)
├── team-membership.entity.ts     # TeamMembership join entity
├── team.service.ts               # CRUD + membership management
├── team.resolver.ts              # GraphQL mutations + queries
├── team.loader.ts                # DataLoader for batched lookups
├── team.service.spec.ts          # 25 unit tests
├── team.resolver.spec.ts         # 12 unit tests
└── dto/
    ├── create-team.input.ts      # CreateTeamInput
    ├── update-team.input.ts      # UpdateTeamInput
    └── team-member.input.ts      # Add/Remove/UpdateRole inputs

Error Handling

Frontend UI Components

The Teams and Sub-Groups functionality is implemented in the primary Management Dashboard (/orgs/[slug]/manage) within the Teams & Members tab.

• TeamsPanel.svelte — The root layout containing the list of rendered teams and the form to create new teams.
• TeamCard.svelte — Contains the inner state management for expanding a single team, iterating its memberships, deleting the team, and role management.

The UI integrates fully with organizations.ts GraphQL queries.

Testing

Running Tests

# Unit tests
npm run test -- apps/organizations

# E2E tests
npx jest --config apps/organizations/test/jest-e2e.json --testPathPattern=teams

Note: E2E tests use in-memory MongoDB and mock the ALERTS_SERVICE TCP client since the Alerts service isn't running during test execution.

Related

• Custom RBAC — Admin-defined custom roles with configurable permission matrices that layer on top of team membership
• Organizations & Permissions — Base roles, vertical roles, and the PermissionsGuard infrastructure
• Corporate Identity (SAML & SCIM) — Enterprise provisioning that auto-creates Teams via SCIM Group sync
• SCIM — Provisioning Engine — SCIM Groups map to Teams via the externalId field
• Organization & Malet Management — Frontend management UI for Organizations, activity feeds, and billing
• Edit History Audit Trail — Field-level change tracking and the cross-entity maletActivityFeed
• Entertainment & Experiences — Entertainment Malet teams use maletIds scoping for venue staff organization
• Professional Services & Client Portals — Professional Malet teams manage client engagements and document vaults
• Wellness & Beauty — Wellness Malet teams organize practitioners for service-linked booking
• Culture & Arts — Culture Malet teams organize curators and artists for exhibitions and events
• Tech & Electronics — Tech Malet teams manage support staff for warranty claims and repairs
• Arcade & Gaming — Arcade Malet teams organize game studio staff for launches and key distribution
• User Identity Resolution — TeamCard.svelte uses profileResolver.ts to display member handles instead of raw UUIDs
• Vertical Seeding Infrastructure — Multi-tenant test data seeding with simulated org teams and malet ownership