Team Collaboration

Team Collaboration Use Cases

This document describes real-world scenarios for team collaboration in Global Watch, including team creation, member management, invitations, and role assignments.

UC-101: Create Team Account

Description

User creates a new team account (workspace) for collaborative forest monitoring. The system creates the account, assigns ownership, and sets up default roles.

Actors

• Primary: Authenticated User
• Secondary: Onboarding System

Preconditions

• User is authenticated
• User has completed personal account setup
• Team accounts feature is enabled

Postconditions

• Team account created with unique slug
• User assigned as team owner
• Default roles configured
• Team workspace accessible via subdomain

Main Flow

1. User navigates to team creation
2. User enters team details:
   • Name: "Acme Corporation"
   • Slug: Auto-generated as acme-corporation
3. System validates slug uniqueness
4. System creates team account
5. System assigns user as owner
6. System creates default roles (owner, admin, member)
7. User is redirected to team dashboard
8. Team accessible at acme-corporation.global.watch

Alternative Flows

A1: Slug Already Exists

1. User enters team name
2. Auto-generated slug conflicts with existing team
3. System shows error: "This team URL is already taken"
4. User manually edits slug
5. Continue from step 3 of main flow

A2: Reserved Slug

1. User enters team name that generates reserved slug
2. System shows error: "This team name is reserved"
3. User chooses different name
4. Continue from step 2 of main flow

Business Rules

Reserved Slugs

The following slugs cannot be used for team accounts:

app, www, api, admin, auth, cdn, assets, asset, static,
docs, blog, help, support, status, mail, ftp, workspace,
map, maps, report, reports

UC-102: Invite Team Member

Description

Team owner or admin invites a new user to join the team. The system sends an invitation email and creates a pending invitation record.

Actors

• Primary: Team Owner/Admin
• Secondary: Email System, Invited User

Preconditions

• User is authenticated
• User has invites.manage permission
• Team has available member slots (if limited)

Postconditions

• Invitation record created
• Invitation email sent
• Invitation expires after 7 days

Main Flow

1. Admin navigates to team members page
2. Admin clicks "Invite Member"
3. Admin enters invitation details:
   • Email: alice@example.com
   • Role: Member (or Admin)
4. System validates email format
5. System checks if user already a member
6. System creates invitation record
7. System sends invitation email
8. Admin sees success message
9. Invitation appears in pending list

Alternative Flows

A1: User Already Member

1. Admin enters email of existing member
2. System shows error: "User is already a team member"
3. Use case ends

A2: Invalid Email

1. Admin enters invalid email format
2. System shows validation error
3. Admin corrects email
4. Continue from step 4 of main flow

A3: Role Hierarchy Violation

1. Admin tries to invite user with higher role
2. System shows error: "Cannot invite with role higher than your own"
3. Admin selects appropriate role
4. Continue from step 4 of main flow

Business Rules

Invitation Email

Subject: You've been invited to join [Team Name] on Global Watch

Hi,

[Inviter Name] has invited you to join [Team Name] on Global Watch.

Click the link below to accept the invitation:
[Accept Invitation Button]

This invitation expires in 7 days.

If you didn't expect this invitation, you can ignore this email.

Best,
The Global Watch Team

UC-103: Accept Invitation

Description

User accepts a team invitation and joins the team with the assigned role.

Actors

• Primary: Invited User
• Secondary: Team Account

Preconditions

• Valid invitation exists
• Invitation has not expired
• User is authenticated (or will authenticate)

Postconditions

• User added as team member
• Invitation marked as accepted
• User can access team workspace

Main Flow

1. User clicks invitation link in email
2. System validates invitation token
3. If user not authenticated:
   • User signs in or creates account
4. System displays invitation details:
   • Team name
   • Inviter name
   • Assigned role
5. User clicks "Accept Invitation"
6. System creates membership record
7. System marks invitation as accepted
8. User is redirected to team dashboard

Alternative Flows

A1: Invitation Expired

1. User clicks invitation link
2. System detects invitation expired
3. System shows error: "This invitation has expired"
4. System suggests contacting team admin
5. Use case ends

A2: Invitation Already Accepted

1. User clicks invitation link
2. System detects invitation already accepted
3. System redirects to team dashboard
4. Use case ends

A3: User Already Member

1. User clicks invitation link
2. System detects user is already a member
3. System shows message: "You're already a member of this team"
4. System redirects to team dashboard
5. Use case ends

Business Rules

UC-104: Update Member Role

Description

Team admin changes a member's role within the team.

Actors

• Primary: Team Owner/Admin
• Secondary: Target Member

Preconditions

• User is authenticated
• User has roles.manage permission
• Target member exists
• Target member has lower role hierarchy

Postconditions

• Member role updated
• Permissions updated accordingly
• Audit log entry created

Main Flow

1. Admin navigates to team members page
2. Admin locates target member
3. Admin clicks "Change Role"
4. Admin selects new role from dropdown
5. System validates role change is allowed
6. System updates member role
7. System logs change to audit log
8. Admin sees success message
9. Member's permissions updated immediately

Alternative Flows

A1: Cannot Modify Higher Role

1. Admin attempts to change role of owner
2. System shows error: "Cannot modify users with equal or higher role"
3. Use case ends

A2: Cannot Promote Above Own Role

1. Admin attempts to promote member to owner
2. System shows error: "Cannot assign role higher than your own"
3. Admin selects appropriate role
4. Continue from step 5 of main flow

Business Rules

Role Hierarchy

owner (hierarchy_level: 1)     ← Highest privilege
  ↓
admin (hierarchy_level: 2)
  ↓
manager (hierarchy_level: 3)
  ↓
member (hierarchy_level: 4)    ← Lowest privilege

UC-105: Remove Team Member

Description

Team admin removes a member from the team.

Actors

• Primary: Team Owner/Admin
• Secondary: Target Member

Preconditions

• User is authenticated
• User has members.manage permission
• Target member exists
• Target member is not the primary owner

Postconditions

• Member removed from team
• Member loses access to team resources
• Audit log entry created

Main Flow

1. Admin navigates to team members page
2. Admin locates target member
3. Admin clicks "Remove Member"
4. System shows confirmation dialog:
   • "Remove [Name] from [Team]?"
   • "They will lose access to all team resources."
5. Admin confirms removal
6. System deletes membership record
7. System logs removal to audit log
8. Admin sees success message
9. Member can no longer access team

Alternative Flows

A1: Cannot Remove Owner

1. Admin attempts to remove primary owner
2. System shows error: "Cannot remove the team owner"
3. Use case ends

A2: Cannot Remove Self

1. Admin attempts to remove themselves
2. System shows error: "Cannot remove yourself from the team"
3. Use case ends

A3: Cannot Remove Higher Role

1. Admin attempts to remove user with higher role
2. System shows error: "Cannot remove users with equal or higher role"
3. Use case ends

Business Rules

UC-106: Transfer Team Ownership

Description

Team owner transfers ownership to another team member.

Actors

• Primary: Current Team Owner
• Secondary: New Owner

Preconditions

• User is the primary team owner
• Target user is a team member
• OTP verification enabled

Postconditions

• Ownership transferred to new user
• Previous owner becomes admin
• Audit log entry created

Main Flow

1. Owner navigates to team settings
2. Owner clicks "Transfer Ownership"
3. Owner selects new owner from member list
4. System shows confirmation with warnings:
   • "This action cannot be undone"
   • "You will become an admin"
5. Owner enters OTP code for verification
6. System validates OTP
7. System transfers ownership
8. System demotes previous owner to admin
9. System logs transfer to audit log
10. Both users notified of change

Alternative Flows

A1: Invalid OTP

1. Owner enters incorrect OTP
2. System shows error: "Invalid verification code"
3. Owner retries or cancels
4. After 3 failures, use case ends

A2: Target Not a Member

1. Owner selects user not in team
2. System shows error: "User must be a team member"
3. Use case ends

Business Rules

UC-107: Onboarding Flow

Description

New user completes onboarding to set up personal and team accounts.

Actors

• Primary: New User
• Secondary: Onboarding System

Preconditions

• User has verified email
• User has not completed onboarding

Postconditions

• Personal account created
• Team account created (optional)
• User redirected to main app

Main Flow

1. User completes email verification
2. System redirects to onboarding
3. Step 1: Profile Setup
   • User enters name: "John Doe"
   • Live preview: app.global.watch/john-doe
   • User clicks "Next"
4. System creates personal account
5. Step 2: Team Setup
   • User enters team name: "Acme Corporation"
   • Live preview: acme-corporation.global.watch
   • User clicks "Complete"
6. System creates team account
7. System assigns user as team owner
8. System creates membership record
9. User redirected to main dashboard

Alternative Flows

A1: Skip Team Creation

1. User completes Step 1
2. User clicks "Skip" on Step 2
3. Only personal account created
4. User can create team later

A2: Personal Account Creation Fails

1. User completes Step 1
2. System fails to create personal account
3. System shows error: "Could not create personal account"
4. User can retry with different name

A3: Team Account Creation Fails

1. User completes Step 1 (personal account created)
2. User completes Step 2
3. System fails to create team account
4. System shows error: "Could not create team workspace"
5. Personal account preserved
6. User can retry team creation

Business Rules

Database State After Onboarding

-- auth.users
id: "123e4567-e89b-12d3-a456-426614174000"
email: "john.doe@example.com"

-- accounts (personal)
id: "123e4567-e89b-12d3-a456-426614174000" -- Same as user_id
name: "John Doe"
slug: "john-doe"
is_personal_account: true

-- accounts (team)
id: "987fcdeb-51a2-43f1-b456-426614174999"
name: "Acme Corporation"
slug: "acme-corporation"
is_personal_account: false

-- memberships
account_id: "987fcdeb-51a2-43f1-b456-426614174999"
user_id: "123e4567-e89b-12d3-a456-426614174000"
account_role: "owner"

Testing Checklist

Team Creation

• Team created with unique slug
• Reserved slugs rejected
• Owner assigned automatically
• Default roles created
• Subdomain accessible

Invitations

• Invitation email sent
• Token validation works
• Expiration enforced (7 days)
• Duplicate invitations handled
• Role hierarchy respected

Member Management

• Role changes work correctly
• Cannot modify higher roles
• Cannot remove owner
• Audit log entries created
• Permissions update immediately

Onboarding

• Personal account created
• Team account created (optional)
• Membership assigned correctly
• Rollback on failure
• Skip team option works

Related Documentation

• Project Management Use Cases
• Multi-Tenancy Architecture
• Database Architecture