# Blind Mode Feature for Team Sessions

## Overview

The Blind Mode feature allows researchers to control whether team members can see each other's card placements during collaborative card sorting sessions. This prevents groupthink and bias while still enabling collaborative research.

## Feature Description

### Two Modes

**1. Collaborative Mode (Default)** 👁️
- All participants see all card placements from all team members
- Real-time vote counts are visible to everyone
- Encourages discussion and consensus building
- Original behavior of team sessions

**2. Blind Mode** 🔒
- Each participant only sees their own card placements
- Participants cannot see where others have placed cards
- Prevents bias and groupthink
- Researcher/monitor still sees ALL votes in aggregate
- Enables independent decision making

## How to Use

### 1. Database Setup

First, run the SQL migration to add the `blind_mode` column to your database:

```sql
-- Run this in phpMyAdmin or your MySQL client
-- File: scripts/team_blind_mode_migration.sql

ALTER TABLE `team_sessions` 
ADD COLUMN `blind_mode` TINYINT(1) NOT NULL DEFAULT 0 
COMMENT '0 = collaborative (all see all votes), 1 = blind (participants only see own votes)' 
AFTER `status`;
```

### 2. Toggle During Active Session

1. Go to the **Team Sessions** management page for your study
2. Find an active team session
3. Look for the **Blind Mode Toggle Switch** next to each session
4. Click the toggle to switch between modes:
   - **OFF (Collaborative)**: 👁️ Collaborative - everyone sees all votes
   - **ON (Blind Mode)**: 🔒 Blind Mode - participants only see their own votes

### 3. Monitor the Session

When monitoring a team session:
- The **Monitor Live** page displays a "Visibility Mode" indicator
- Shows current mode: Collaborative 👁️ or Blind Mode 🔒
- Researcher always sees complete aggregated vote data regardless of mode

## User Experience

### For Participants

**In Collaborative Mode:**
```
Team Voting: Drag cards to categories to vote. Vote counts update in real-time!
```
- See all cards placed by all team members
- Vote counts show how many people voted for each placement
- Can see trends and popular choices

**In Blind Mode:**
```
🔒 Blind Mode: You can only see your own card placements. 
Others cannot see where you place cards.
```
- Only see their own card placements
- Cannot see other participants' choices
- Vote counts only show "1" for their own placements
- Encourages independent thinking

### For Researchers

**Team Sessions Management Page:**
- Toggle switch visible for each active session
- Visual feedback when toggling (green flash on success)
- Icon changes: 👁️ for Collaborative, 🔒 for Blind Mode
- Real-time mode switching (no page reload needed)

**Monitor Live Page:**
- "Visibility Mode" card shows current mode
- Color-coded: White text for Collaborative, Yellow (#ffc107) for Blind Mode
- Auto-updates every 3 seconds
- All vote data visible regardless of participant mode

## Technical Implementation

### Files Modified

1. **Database Schema**
   - `scripts/team_blind_mode_migration.sql` - Adds blind_mode column

2. **API Endpoints**
   - `public/api/team_session_toggle_blind.php` - NEW: Toggle blind mode
   - `public/api/team_votes_get.php` - MODIFIED: Filters votes based on mode and participant_id

3. **Frontend Pages**
   - `public/team_session.php` - MODIFIED: Added toggle switch UI
   - `public/team_participant.php` - MODIFIED: Passes participant_id, updates banner
   - `public/team_monitor.php` - MODIFIED: Displays mode indicator

4. **Styles**
   - `assets/css/style.css` - MODIFIED: Added toggle switch CSS

### How It Works

**Backend Logic:**
```php
// In team_votes_get.php
if ($blindMode === 1 && $participantId !== '') {
    // Return only this participant's votes
    // vote_count will always be 1
} else {
    // Return all votes aggregated (for monitor or collaborative mode)
    // vote_count shows total from all participants
}
```

**Frontend Detection:**
```javascript
// Participant view sends their ID
fetch('./api/team_votes_get.php?team_session_id=X&participant_id=Y')

// Monitor view does NOT send participant_id
fetch('./api/team_votes_get.php?team_session_id=X')
// This ensures monitor always sees all data
```

## Best Practices

### When to Use Collaborative Mode
- Initial brainstorming sessions
- When consensus building is the goal
- Small teams where discussion is expected
- Training sessions where learning from others is valuable

### When to Use Blind Mode
- When unbiased individual input is needed
- Avoiding groupthink in decision-making
- Expert panels where opinions should be independent
- A/B testing different approaches (some blind, some collaborative)
- Initial rounds before revealing group consensus

### Workflow Suggestion
1. **Start in Blind Mode** - Get independent thoughts first
2. **Review aggregate results** - Researcher analyzes without revealing individual votes
3. **Switch to Collaborative Mode** - Open discussion and consensus building
4. **Finalize** - Lock in final group decisions

## Security & Permissions

- **Toggle requires researcher authentication** - Only logged-in researchers can toggle mode
- **Only works on active sessions** - Cannot toggle finalized/completed sessions
- **Participant data privacy** - In blind mode, participants truly cannot see others' data
- **Monitor view protected** - Always requires researcher login

## API Reference

### Toggle Blind Mode
```http
POST /public/api/team_session_toggle_blind.php
Content-Type: application/json

{
  "team_session_id": 123,
  "blind_mode": 1  // 0 = collaborative, 1 = blind
}
```

**Response:**
```json
{
  "ok": true,
  "message": "Session updated to Blind Mode",
  "blind_mode": 1,
  "mode_name": "Blind Mode"
}
```

### Get Votes (with mode awareness)
```http
GET /public/api/team_votes_get.php?team_session_id=123&participant_id=xyz

Response includes:
{
  "ok": true,
  "votes": [...],
  "participant_count": 5,
  "status": "active",
  "blind_mode": 1,
  "filtered_to_participant": true
}
```

## Troubleshooting

**Toggle not appearing?**
- Ensure SQL migration has been run
- Check that session status is "active"
- Verify you're logged in as a researcher

**Participants still seeing all votes?**
- Check that toggle is ON (blue/checked)
- Verify browser has refreshed (or auto-refresh has occurred)
- Check browser console for API errors

**Monitor not showing aggregate data?**
- Ensure monitor page is NOT sending participant_id parameter
- Check that team_votes_get.php returns all votes when no participant_id

## Future Enhancements

Potential improvements:
- [ ] History log of mode changes with timestamps
- [ ] Scheduled mode switching (e.g., auto-switch after 10 minutes)
- [ ] Per-card blind mode (some cards blind, some collaborative)
- [ ] Export mode history in reports
- [ ] Notification to participants when mode changes

---

**Implementation Date:** October 2025  
**Version:** 1.0  
**Status:** Production Ready