Team Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/app/api/teams/route.ts
• src/app/api/teams/[teamId]/users/route.ts
• src/app/api/teams/[teamId]/users/[userId]/route.ts
• src/permissions/team.ts
• src/queries/prisma/team.ts
• src/queries/prisma/teamUser.ts
• src/app/(main)/teams/[teamId]/TeamSettings.tsx
• cypress/e2e/api-team.cy.ts

The Team Management feature in Umami provides a collaborative environment where users can be grouped into teams to share access to websites. This system allows for granular control over user permissions through a role-based access control (RBAC) system, ensuring that team members have appropriate levels of access to team resources.

Functionality includes creating and deleting teams, managing team membership (adding, updating, and removing users), and assigning roles. All websites associated with a team are accessible to its members, facilitating shared analytics and management.

Data Model

The team management functionality is primarily supported by the Team and TeamUser database models. These models establish the relationships between teams, users, and their associated roles.

The following diagram illustrates the entity relationships for the team management feature.

Team*: Represents a team entity. It contains a name and an optional accessCode for joining.

• TeamUser: A join table that links a User to a Team and assigns them a specific role.
• Website: Can be associated with a Team, making it a shared resource.

Sources: src/queries/prisma/team.ts, src/queries/prisma/teamUser.ts, cypress/e2e/api-website.cy.ts:60-75

Roles and Permissions

Access control within a team is managed through a set of predefined roles. These roles determine what actions a user can perform on a team and its associated resources. The primary permission-checking functions are canViewTeam, canUpdateTeam, canDeleteTeam, and canDeleteTeamUser.

Sources: src/permissions/team.ts, src/app/(main)/teams/[teamId]/TeamSettings.tsx:18-29

Role	Constant	View Team	Update Team	Delete Team	Manage Members	Description
Team Owner	teamOwner	✅	✅	✅	✅	Full control over the team, including deletion. The user who creates the team is automatically assigned this role.
Team Manager	teamManager	✅	✅	❌	✅	Can manage team settings and members, but cannot delete the team.
Team Member	teamMember	✅	❌	❌	❌	Can view team resources (like websites) but cannot change team settings or manage members.
Team View Only	teamViewOnly	✅	❌	❌	❌	Can only view team resources. This role is functionally similar to teamMember regarding team permissions.

The permission logic is implemented in src/permissions/team.ts:

• canViewTeam: Checks if the user is a member of the team.
• canUpdateTeam: Checks if the user is a teamOwner or teamManager.
• canDeleteTeam: Checks if the user is a teamOwner.
• canDeleteTeamUser: Checks if the user is a teamOwner or teamManager.

Sources: src/permissions/team.ts:4-44, src/components/messages.ts:38-42

API Endpoints

The Team Management feature is exposed through a set of RESTful API endpoints. These endpoints handle all CRUD (Create, Read, Update, Delete) operations for teams and their members.

Sources: cypress/e2e/api-team.cy.ts, src/app/api/teams/route.ts, src/app/api/teams/[teamId]/users/route.ts, src/app/api/teams/[teamId]/users/[userId]/route.ts

Team Endpoints

Method	Path	Description
POST	/api/teams	Creates a new team. The creator is automatically made the teamOwner.
GET	/api/teams/{teamId}	Retrieves the details for a specific team.
POST	/api/teams/{teamId}	Updates a team's properties, such as its name.
DELETE	/api/teams/{teamId}	Deletes a team. This action is restricted to the teamOwner.

Team Member Endpoints

Method	Path	Description
GET	/api/teams/{teamId}/users	Retrieves a paginated list of all users in a team.
POST	/api/teams/{teamId}/users	Adds a new user to a team with a specified role.
GET	/api/teams/{teamId}/users/{userId}	Retrieves a specific user's membership details within a team, including their role.
POST	/api/teams/{teamId}/users/{userId}	Updates a user's role within a team.
DELETE	/api/teams/{teamId}/users/{userId}	Removes a user from a team.

Team Resource Endpoints

Method	Path	Description
GET	/api/teams/{teamId}/websites	Retrieves a list of all websites that belong to a team.

Core Workflows

Team Creation

When a user creates a team, the system performs two database operations within a single transaction: creating the Team record and creating the TeamUser record to assign the creator as the teamOwner.

This diagram shows the sequence for creating a team.

Adding a User to a Team

A teamOwner or teamManager can add other users to the team. The API first checks if the requesting user has the necessary permissions and then verifies that the target user is not already a member before creating the new TeamUser record.

This diagram shows the flow for adding a user to a team.

Team Deletion

Only a teamOwner can delete a team. The deletion process differs based on the application's deployment mode.

• Standard Mode: The system executes a transaction to delete all associated TeamUser records and then the Team record itself.
• Cloud Mode: The team is soft-deleted by setting the deletedAt timestamp. This preserves the data while making the team inactive.

Sources: src/queries/prisma/team.ts:138-166, src/permissions/team.ts:34-44

Frontend Components

The user interface for team management is built with several React components that handle displaying team information and interacting with the API.

• TeamSettings.tsx: The main view for a specific team. It uses hooks like useTeam and useLoginQuery to fetch data and determine the current user's permissions (isTeamOwner, canEdit). Based on these permissions, it conditionally renders other components like TeamEditForm, TeamMembersDataTable, and TeamManage.
  Sources: [src/app/(main)/teams/[teamId]/TeamSettings.tsx]
• TeamEditForm.tsx: Allows users with sufficient permissions to update a team's name and regenerate its access code. It uses the useUpdateQuery hook to post changes to the /api/teams/{teamId} endpoint.
  Sources: [src/app/(main)/teams/[teamId]/TeamEditForm.tsx]
• TeamMembersDataTable.tsx: Renders a table of team members, showing their username and role. For users with edit permissions, it includes buttons to edit or remove a member.
  Sources: [src/app/(main)/teams/[teamId]/TeamSettings.tsx:35]
• TeamMemberEditForm.tsx: A form presented in a modal or popover that allows a teamManager or teamOwner to change another member's role.
  Sources: [src/app/(main)/teams/[teamId]/TeamMemberEditForm.tsx]

Summary

The Team Management module is a critical feature for enabling collaboration in Umami. It leverages a straightforward data model and a clear, role-based permission system to provide a secure and flexible way for users to share and manage website analytics. The feature is supported by a comprehensive set of API endpoints and a modular frontend architecture, allowing for robust and maintainable team functionality.