# Project Team Model

## Overview

The Project Team Model defines how users interact with projects, sprints, and work items in MVNexus's Agile module. It establishes clear relationships between:

- **Projects** and their **Members**
- **Sprints** and their **Participants**
- **Work Items** and their **Assignees**, **Collaborators**, and **Watchers**

## Core Principles

### Project Membership vs Sprint Participation

These are **not the same thing**:

| Concept | Scope | Purpose |
|---------|-------|---------|
| **Project Member** | Project-level | Everyone allowed to participate in the project |
| **Sprint Participant** | Sprint-level | Subset of members actively working in a specific sprint |

### Work Item Ownership Model

```
Work Item
├── Assignee (exactly 1) — Single owner responsible for delivery
├── Collaborators (0-N) — Supporting contributors who can work on the item
└── Watchers (0-N) — Observers who receive notifications only
```

## Entity Relationships

```
┌─────────────────────────────────────────────────────────────────┐
│                           PROJECT                               │
├─────────────────────────────────────────────────────────────────┤
│  owner_user_id ─────────────────────────────────► User          │
│                                                                 │
│  ┌─────────────────┐                                           │
│  │ ProjectMembers  │ ─► user_id, role (owner/manager/member/   │
│  │                 │    viewer), added_by_user_id              │
│  └────────┬────────┘                                           │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────┐                                           │
│  │     Sprints     │                                           │
│  │                 │                                           │
│  │  ┌────────────┐ │                                           │
│  │  │Participants│ │ ─► user_id, capacity_md (subset of        │
│  │  │            │ │    project members)                       │
│  │  └────────────┘ │                                           │
│  │                 │                                           │
│  │  ┌────────────┐ │                                           │
│  │  │  Tickets   │ │ ─► current_assignee_id, collaborators,   │
│  │  │            │ │    watchers                               │
│  │  └────────────┘ │                                           │
│  └─────────────────┘                                           │
└─────────────────────────────────────────────────────────────────┘
```

## Project Roles

| Role | Permissions |
|------|------------|
| **Owner** | Full control over project, members, sprints, work items |
| **Manager** | Manage work items, sprints, capacity planning |
| **Member** | Work on assigned items, view project data |
| **Viewer** | Read-only access to project data |

### Permission Matrix

| Action | Owner | Manager | Member | Viewer |
|--------|-------|---------|--------|--------|
| Manage project settings | ✓ | ✗ | ✗ | ✗ |
| Manage members | ✓ | ✓ | ✗ | ✗ |
| Plan capacity | ✓ | ✓ | ✗ | ✗ |
| Create/edit work items | ✓ | ✓ | ✓ | ✗ |
| Assign work | ✓ | ✓ | ✗ | ✗ |
| View project | ✓ | ✓ | ✓ | ✓ |

## Database Schema

### project_members

```sql
CREATE TABLE project_members (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id) CASCADE,
    user_id UUID REFERENCES users(id) RESTRICT,
    role VARCHAR(20) DEFAULT 'member',
    added_by_user_id UUID REFERENCES users(id),
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    UNIQUE(project_id, user_id)
);
```

### project_sprint_participants

```sql
CREATE TABLE project_sprint_participants (
    id UUID PRIMARY KEY,
    project_sprint_id UUID REFERENCES project_sprints(id) CASCADE,
    user_id UUID REFERENCES users(id) RESTRICT,
    capacity_md DECIMAL(6,2) NULL,
    added_by_user_id UUID REFERENCES users(id),
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    UNIQUE(project_sprint_id, user_id)
);
```

### ticket_watchers

```sql
CREATE TABLE ticket_watchers (
    id UUID PRIMARY KEY,
    ticket_id UUID REFERENCES tickets(id) CASCADE,
    user_id UUID REFERENCES users(id) RESTRICT,
    added_by_user_id UUID REFERENCES users(id),
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    UNIQUE(ticket_id, user_id)
);
```

## API Endpoints

### Project Members

```
GET    /api/v1/projects/{project}/members
POST   /api/v1/projects/{project}/members
PATCH  /api/v1/projects/{project}/members/{user}
DELETE /api/v1/projects/{project}/members/{user}
```

### Sprint Participants

```
GET    /api/v1/projects/{project}/sprints/{sprint}/participants
POST   /api/v1/projects/{project}/sprints/{sprint}/participants
PATCH  /api/v1/projects/{project}/sprints/{sprint}/participants/{user}
DELETE /api/v1/projects/{project}/sprints/{sprint}/participants/{user}
PUT    /api/v1/projects/{project}/sprints/{sprint}/participants/sync
```

### Ticket Watchers

```
GET    /api/v1/tickets/{ticket}/watchers
POST   /api/v1/tickets/{ticket}/watchers
DELETE /api/v1/tickets/{ticket}/watchers/{user}
POST   /api/v1/tickets/{ticket}/watchers/toggle
GET    /api/v1/tickets/{ticket}/watchers/status
```

## Frontend Components

### Team Tab (`/projects/:id/team`)

The central hub for team management, containing:

1. **Team Summary Cards**
   - Total Members
   - Active Sprint Participants
   - Managers
   - Available Capacity

2. **Members Table**
   - Avatar, Name, Email
   - Project Role
   - Capacity, Workload
   - Utilization %
   - Status (Available/Busy/Overloaded)
   - Actions (Edit/Remove)

3. **Workload View**
   - Per-member metrics
   - Health indicators (Green/Yellow/Red)
   - Sprint participation status

## Lifecycle Examples

### Adding a New Team Member

1. Navigate to Project → Team tab
2. Click "Add Member"
3. Search for user (must be in same company/department)
4. Select role (Member/Manager/Viewer)
5. User appears in members list
6. User can now be added to sprints as a participant

### Selecting Sprint Participants

1. Navigate to Sprint Details
2. Open Participants panel
3. Select from project members
4. Set capacity (MD) for each participant
5. Only participants contribute to sprint capacity/velocity

### Assigning Work

1. Work item can only be assigned to project members
2. Validation prevents assignment to non-members
3. Error message: "User must be added to the project before assignment"