PSA/ee/docs/plans/2026-02-26-teams-v2-org-hierarchy-operational-teams/PRD.md

PRD — Teams V2: Organizational Hierarchy + Operational Teams

• Slug: teams-v2
• Date: 2026-02-26
• Status: Draft

Summary

Split the existing single "teams" concept into two distinct structures:

1. "Reports To" (Organizational Hierarchy) — A reports_to field on each user forming a manager-subordinate tree. Drives org chart display, timesheet approval chains, and scheduling scope.
2. "Teams" (Functional/Operational Groups) — Repurpose existing teams as cross-functional groups that can be assigned to tickets and project tasks as a unit. Team lead auto-becomes primary assignee. Members are expanded into ticket_resources.

All new UI elements are gated behind a teams-v2 PostHog feature flag. Schema migrations are additive and not gated.

Problem

The current team system is a settings-only feature disconnected from day-to-day workflows:

• Teams cannot be assigned to tickets or tasks — work assignment is individual-only
• Timesheet approval is tightly coupled to team manager, but there's no formal org hierarchy — if a user's manager changes, you have to restructure teams
• There's no org chart visualization
• Manager-of-manager cannot approve subordinates' timesheets (no transitive authority)
• Several API endpoints reference non-existent database tables and crash at runtime

Goals

1. Introduce a reports_to relationship on users to model organizational hierarchy
2. Auto-seed reports_to from existing team/manager data (zero customer effort)
3. Enable timesheet approval via the reports_to chain (transitive — manager of manager can approve)
4. Provide org chart visualization in User Management
5. Enable assigning an entire team to a ticket or project task
6. When a team is assigned, auto-set team lead as primary assignee and expand members into ticket resources
7. Provide a new UserAndTeamPicker component that shows both users and teams
8. Show team badge on the "Agent team" card in ticket detail
9. Enhance the "Assigned To" ticket list filter to include teams
10. Gate all new UI behind a feature flag for safe, gradual rollout

Non-goals

• Team logos or custom team icons (use generic team icon only)
• Team-based reporting or analytics dashboards
• Team notifications on assignment
• Team-based dispatch filtering
• Workflow automation with team routing rules
• "My Team" ticket queue view
• Cleaning up broken API endpoints (deferred to Phase 3)
• Removing the existing team-manager approval path (kept for backwards compatibility)

Users and Primary Flows

Personas

• MSP Admin — Sets up org structure and teams. Manages user profiles.
• Team Manager / Lead — Approves timesheets for direct reports. Leads a functional team.
• Technician / Agent — Works on assigned tickets. May belong to one or more teams.

Primary Flows

Flow 1: Admin sets up "Reports To" hierarchy

1. Admin opens User Management
2. Edits a user profile
3. Sets the "Reports To" dropdown to select their manager
4. Views the org chart tab to verify the hierarchy looks correct

Flow 2: Manager approves timesheets via reporting chain

1. Manager opens timesheet approval dashboard
2. Sees timesheets from all direct and indirect reports (via reports_to chain)
3. Approves or requests changes as usual

Flow 3: Agent assigns a team to a ticket

1. Agent opens a ticket
2. In the "Assigned To" field, the UserAndTeamPicker shows users and teams
3. Agent selects "Network Team"
4. System sets assigned_team_id, makes team lead the primary assignee (if empty), and adds all other members as additional agents
5. Team badge appears on the "Agent team" card

Flow 4: Agent removes a team from a ticket

1. Agent clicks "x" on the team badge
2. Confirmation dialog appears with options:
   • Remove all team members from assignment
   • Keep all team members as individual agents
   • Select individual members to keep/remove
3. Agent makes selection, assigned_team_id is cleared

Flow 5: Filtering tickets by team

1. Agent opens ticket list
2. Uses the "Assigned To" filter which now shows teams alongside users
3. Selects a team to see all tickets assigned to that team

UX / UI Notes

Reports To

• "Reports To" dropdown on the user edit form — standard dropdown selecting from all users in the tenant
• Org chart tab in User Management — tree view visualization of reporting lines (read-only)

Team Assignment

• UserAndTeamPicker — new component replacing UserPicker via feature flag swap:

  {featureFlag('teams-v2')
    ? <UserAndTeamPicker ... />
    : <UserPicker ... />}
  

  • Users section first, teams section below with separator
  • Teams show member count and lead name
  • Generic team icon for teams vs. user avatar for individuals

• Team badge on "Agent team" card — chip/badge following existing Additional Agents pattern (initials/icon + name + x button). Uses same chip styling as the existing MultiUserPicker chips (the bg-gray-100 rounded-full pill pattern).

• Team removal dialog — confirmation dialog with radio buttons:

  • "Remove all team members"
  • "Keep all team members as individual agents"
  • Individual checkboxes for each team member

• "Assigned To" filter enhancement — existing MultiUserPicker filter in TicketingDashboard.tsx enhanced to show teams in the dropdown alongside users when flag is on.

• All new UI must follow established component variants, color schemes, and interaction patterns.

Requirements

Functional Requirements

Phase 1: Reports To + Org Hierarchy

• FR-1.1: Add nullable reports_to UUID column to users table referencing users(user_id)
• FR-1.2: Auto-seed reports_to from existing team membership data in the migration (team member → team manager_id)
• FR-1.3: Validate that setting reports_to doesn't create circular chains
• FR-1.4: Add "Reports To" dropdown field on user edit form (behind feature flag)
• FR-1.5: Build org chart tree view in User Management (behind feature flag)
• FR-1.6: Add isInReportsToChain() function for transitive approval check
• FR-1.7: Extend canApprove logic: existing team-manager check (always active) + reports_to chain check (behind feature flag)
• FR-1.8: Update fetchTimeSheetsForApproval() to include timesheets from reports_to subordinates when flag is on
• FR-1.9: Update AvailabilitySettings to additionally scope by reports_to when flag is on
• FR-1.10: Update SchedulePage to additionally scope by reports_to when flag is on

Phase 2: Operational Teams

• FR-2.1: Add role TEXT DEFAULT 'member' column to team_members table
• FR-2.2: Migration: set role = 'lead' for existing team members whose user_id matches teams.manager_id
• FR-2.3: Add nullable assigned_team_id UUID column to tickets table referencing teams(team_id)
• FR-2.4: Add nullable assigned_team_id UUID column to project_tasks table referencing teams(team_id)
• FR-2.5: Implement team assignment action: sets assigned_team_id, assigns lead as primary (if assigned_to is NULL), expands other members into ticket_resources with role = 'team_member'
• FR-2.6: When assigning team and assigned_to is already set: add all team members as resources EXCEPT whoever is already assigned_to
• FR-2.7: Team lead must NOT be added as ticket_resources when they are the primary assignee (DB constraint: assigned_to != additional_user_id)
• FR-2.8: Build UserAndTeamPicker component showing users and teams in grouped sections (behind feature flag)
• FR-2.9: Feature flag swap: render UserAndTeamPicker instead of UserPicker on ticket/task detail when teams-v2 is enabled
• FR-2.10: Show team badge (chip: generic icon + team name + x) on "Agent team" card when assigned_team_id is set (behind feature flag)
• FR-2.11: Clicking "x" on team badge shows confirmation dialog with removal options
• FR-2.12: "Remove all" option removes ticket_resources with role = 'team_member' and clears assigned_team_id
• FR-2.13: "Keep all" option clears assigned_team_id only, resources stay
• FR-2.14: Individual selection option lets user choose which team members to keep/remove
• FR-2.15: Primary assigned_to is never automatically removed when clearing team assignment
• FR-2.16: Adding/removing individual agents does NOT affect team assignment. Team badge and individual agent chips coexist independently.
• FR-2.17: Team membership is a snapshot at assignment time — later team roster changes don't affect existing ticket resources
• FR-2.18: Enhance "Assigned To" filter in ticket list to show teams alongside users when flag is on
• FR-2.19: Selecting a team in the filter → filters by tickets.assigned_team_id
• FR-2.20: Extend tickets.create workflow action to support assignee: { type: 'team', id: uuid } (matching projects.create_task pattern)
• FR-2.21: Update ITicket and IProjectTask interfaces to include assigned_team_id
• FR-2.22: Update tenant export to include new columns (reports_to, assigned_team_id, role)

Non-functional Requirements

• NFR-1: All new UI elements gated behind teams-v2 PostHog feature flag
• NFR-2: Schema migrations are additive (nullable columns) and not feature-flag-gated
• NFR-3: Existing team-manager timesheet approval logic remains active and unchanged
• NFR-4: Multi-tenant isolation preserved — all queries tenant-scoped
• NFR-5: isInReportsToChain() must handle arbitrarily deep hierarchies without stack overflow (use iterative/CTE approach)

Data / API / Integrations

Schema Changes

-- Phase 1
ALTER TABLE users ADD COLUMN reports_to UUID REFERENCES users(user_id);

-- Auto-seed
UPDATE users u SET reports_to = t.manager_id
FROM team_members tm
JOIN teams t ON t.team_id = tm.team_id AND t.tenant = tm.tenant
WHERE u.user_id = tm.user_id AND u.tenant = tm.tenant AND u.user_id != t.manager_id;

-- Phase 2
ALTER TABLE team_members ADD COLUMN role TEXT NOT NULL DEFAULT 'member';
UPDATE team_members tm SET role = 'lead'
FROM teams t WHERE tm.team_id = t.team_id AND tm.tenant = t.tenant AND tm.user_id = t.manager_id;

ALTER TABLE tickets ADD COLUMN assigned_team_id UUID REFERENCES teams(team_id);
ALTER TABLE project_tasks ADD COLUMN assigned_team_id UUID REFERENCES teams(team_id);

Affected Interfaces

• IUser — add reports_to?: string
• ITeam — existing, no change needed (manager_id stays as team lead reference)
• ITeamMember — add role: 'member' | 'lead'
• ITicket — add assigned_team_id?: string
• IProjectTask — add assigned_team_id?: string
• ITicketResource — role field will use 'team_member' value for team-assigned resources

API Considerations

• Existing team CRUD endpoints unchanged
• New server actions needed: assignTeamToTicket(), removeTeamFromTicket(), getReportsToChain()
• Existing addTicketResource() reused for individual member expansion

Security / Permissions

• reports_to changes: require user edit permission
• Team assignment on tickets: require ticket edit permission (same as changing assigned_to)
• Timesheet approval via reports_to: require timesheet:approve permission (existing)
• Cycle prevention on reports_to: server-side validation, not client-only
• All queries continue to be tenant-scoped via RLS policies

Rollout / Migration

Migration Safety

• All schema changes are additive nullable columns — no data loss, no breaking changes
• reports_to auto-seeded in migration from existing team data (verified safe for all active tenants)
• All UI behind feature flag — invisible until enabled
• Existing approval logic untouched — works in parallel

Rollout Plan

1. Deploy migrations (schema + data seed) — invisible to users
2. Enable teams-v2 flag on staging for internal testing
3. Enable flag on Nine Minds tenant for dogfooding
4. Gradual per-tenant rollout to customers
5. Once stable, remove flag gates and make generally available

Open Questions

None — all questions resolved during analysis phase.

Acceptance Criteria (Definition of Done)

1. reports_to column exists on users and is auto-seeded from existing team data
2. Setting reports_to rejects circular chains
3. Org chart view displays the reporting hierarchy correctly
4. Managers can approve timesheets for direct and indirect reports via reports_to chain
5. A team can be assigned to a ticket, setting team lead as primary and expanding members into resources
6. Team badge appears on "Agent team" card with working "x" removal
7. Team removal dialog offers all three options and executes correctly
8. UserAndTeamPicker shows users and teams, swaps correctly via feature flag
9. "Assigned To" filter includes teams when flag is on
10. All new UI is invisible when teams-v2 flag is off
11. Existing team-manager approval continues to work unchanged
12. No regressions in existing ticket assignment, resource management, or timesheet approval