colleague visibility

# Live Colleague Feed (Phase 3, 4 & 5)

## Overview

The live colleague feed shows employees and admins who is currently logged in with real-time updates. Phase 3 added employee view, Phase 4 added enhanced admin view with timestamps, and Phase 5 made it live with auto-refresh.

## Purpose

- **Real-time awareness** - Know who's working right now
- **Collaboration** - See who's available for questions/help
- **Social connection** - Feel part of the team
- **Transparency** - Open workplace culture
- **Admin oversight** - HR tracks live attendance

## How It Works

### Employee View

**Where**: Employee dashboard after successful login (`/<company>/login`)

**When**: Immediately after clock-in

**Visibility**: Controlled by admin toggle (enabled by default)

**Information Displayed:**
- First name
- Last name
- Count of currently logged-in colleagues

**Updates**: Auto-refreshes every 5 seconds without page reload

**Shows**: Only employees currently logged in (not logged out)

**Privacy**: Only names shown to employees (no timestamps or IDs)

### Admin View

**Where**: Admin dashboard after authentication (`/<company>/admin`)

**When**: Always visible (cannot be disabled)

**Information Displayed:**
- First name
- Last name
- Login timestamp
- Location (if geolocation enabled)
- Count of employees currently logged in

**Updates**: Auto-refreshes every 5 seconds without page reload

**Shows**: Only employees currently logged in (not logged out)

**Sorting**: By most recent login first

**Information NOT Shown to Employees:**
- Clock-in times
- Clock-out times
- Current status (still logged in or not)
- Department or role

## Display Format

### Employee View (Blue Info Box)

```
👥 Colleagues Currently Logged In (5)
─────────────────────────────────
Alice Johnson
Bob Smith
Carol Williams
David Brown
Emma Davis

🔄 Updates every 5 seconds
```

**Features:**
- Alphabetically sorted by first name
- Scrollable list (max 200px height)
- Shows count in header
- Clean, simple layout
- **Live updates** - Auto-refreshes every 5 seconds
- **Real-time** - Only shows currently logged-in employees

### Admin View (Blue Table)

```
👥 Employees Currently Logged In (3)
─────────────────────────────────────────────
Name            User ID    Login Time
Alice Johnson   AJ1456     09:15:23
Bob Smith       BS1457     08:45:12
Carol Williams  CW1458     10:02:45

🔄 Updates every 5 seconds
```

**Features:**
- Sorted by most recent login first
- Table format with headers
- Shows user IDs and timestamps
- Always visible to admin
- **Live updates** - Auto-refreshes every 5 seconds
- **Real-time** - Only shows currently logged-in employees

## User Experience

### Employee Workflow

1. **Employee logs in** - Completes face verification
2. **Dashboard loads** - Shows clock-in confirmation
3. **Colleague list appears** - Blue box below login info (if enabled)
4. **Employee sees team** - Reviews who's working today
5. **Employee continues** - Can view logs or clock out

### Admin Workflow

1. **HR visits admin page** - `/<company>/admin`
2. **Authenticates** - Enters HR credentials
3. **Dashboard loads** - Shows upload form
4. **Employee table appears** - Blue table at top with timestamps
5. **HR sees real-time attendance** - Who's logged in with times
6. **HR continues** - Can upload employees or access settings

## Admin Controls

### Settings Toggle

**Location:** `/<company>/settings`

**Setting:** Employee Colleague Visibility

**Options:**
- **Enabled (Show to Employees)** - Default, employees see colleague list
- **Disabled (Admin Only)** - Only admin sees the list

**Behavior:**
- When **enabled**: Employees see colleague names on their dashboard
- When **disabled**: Employees see nothing, admin still sees full table
- Admin view is **always on** regardless of setting

**Use Cases for Disabling:**
- Privacy-focused workplace culture
- Competitive work environment
- Management preference
- Regulatory requirements

### How to Configure

1. HR visits `/<company>/settings`
2. Scrolls to "Colleague Visibility" section
3. Selects desired option from dropdown
4. Clicks "Save Settings"
5. Changes apply immediately to all employees

### Example Scenarios

**Scenario 1: Employee Logs Out**
```
Before (3 logged in):
👥 Colleagues Currently Logged In (3)
Alice Johnson
Bob Smith
Carol Williams

[Bob logs out]

After (within 5 seconds):
👥 Colleagues Currently Logged In (2)
Alice Johnson
Carol Williams
```
Bob disappears automatically without page refresh.

**Scenario 2: New Employee Logs In**
```
Before (2 logged in):
👥 Colleagues Currently Logged In (2)
Alice Johnson
Carol Williams

[David logs in]

After (within 5 seconds):
👥 Colleagues Currently Logged In (3)
Alice Johnson
Carol Williams
David Brown
```
David appears automatically without page refresh.

**Scenario 3: First to Arrive**
```
👥 Colleagues Currently Logged In (1)
─────────────────────────────────
John Doe
```
Employee sees only themselves (first to clock in).

**Scenario 4: Everyone Logs Out**
```
Before (2 logged in):
👥 Colleagues Currently Logged In (2)
Alice Johnson
Bob Smith

[Both log out]

After (within 5 seconds):
👥 Colleagues Currently Logged In (0)
No one logged in
```
List updates to show empty state.

## Privacy & Security

### What's Protected

✅ **No sensitive data** - Only names shown to employees
✅ **No user IDs** - Employee IDs not displayed to employees
✅ **Real-time only** - Shows current status, not historical
✅ **Live tracking** - Shows who's actively logged in right now
✅ **No timestamps** - Clock-in times not shown to employees
✅ **Login required** - Only visible after authentication

### Data Source

- Queries `<company>_employees_logs` table
- Filters by `DATE(login_time) = CURRENT_DATE`
- Returns distinct `first_name` and `last_name`
- No additional tracking or logging

### Compliance

- **GDPR compliant** - Minimal personal data
- **Workplace transparency** - Legitimate business interest
- **Employee awareness** - Promotes collaboration
- **No surveillance** - Doesn't track activity or status

## Technical Details

### Database Query (Employee View)

```sql
SELECT DISTINCT first_name, last_name
FROM <company>_employees_logs
WHERE DATE(login_time) = CURRENT_DATE
AND logout_time IS NULL
ORDER BY first_name, last_name
```

**Key Filter:** `logout_time IS NULL` ensures only currently logged-in employees are shown.

### Database Query (Admin View)

```sql
SELECT first_name, last_name, user_id, login_time
FROM <company>_employees_logs
WHERE DATE(login_time) = CURRENT_DATE
AND logout_time IS NULL
ORDER BY login_time DESC
```

**Key Filter:** `logout_time IS NULL` ensures only currently logged-in employees are shown.

### Python Functions

**Employee View:**
```python
def get_employees_logged_in_today(company_slug):
    """Get list of employees currently logged in"""
    # Query logs with logout_time IS NULL filter
    # Return first_name|last_name format
```

**Admin View:**
```python
def get_employees_logged_in_today_with_times(company_slug):
    """Get list of employees currently logged in (for admin)"""
    # Query logs with logout_time IS NULL filter
    # Return first_name|last_name|user_id|login_time format
```

### Go API Handlers (Phase 5)

**Employee API:**
```go
func apiLoggedInEmployeesHandler(w http.ResponseWriter, r *http.Request) {
    // Extract company slug
    // Call Python function
    // Return JSON array of LoggedInEmployee
}
```

**Admin API:**
```go
func apiLoggedInEmployeesAdminHandler(w http.ResponseWriter, r *http.Request) {
    // Extract company slug
    // Call Python function
    // Return JSON array of LoggedInEmployeeAdmin
}
```

**API Endpoints:**
- `/<company>/api/logged-in-employees` - Employee view
- `/<company>/api/logged-in-employees-admin` - Admin view

### Frontend JavaScript (Phase 5)

**Employee View:**
```javascript
function updateColleagues() {
    fetch('/' + companySlug + '/api/logged-in-employees')
        .then(response => response.json())
        .then(data => {
            // Update count and list
        });
}

setInterval(updateColleagues, 5000); // Every 5 seconds
```

**Admin View:**
```javascript
function updateEmployees() {
    fetch('/' + companySlug + '/api/logged-in-employees-admin')
        .then(response => response.json())
        .then(data => {
            // Update count and table
        });
}

setInterval(updateEmployees, 5000); // Every 5 seconds
```

### Go Handlers

**Employee Login Handler:**
```go
// Check if visibility enabled
cmd := exec.Command("./venv/bin/python", "face_verify_db.py", 
    "get_colleague_visibility_enabled", companySlug)
visibilityEnabled := strings.TrimSpace(string(output)) == "true"

if visibilityEnabled {
    // Get employees currently logged in
    cmd := exec.Command("./venv/bin/python", "face_verify_db.py", 
        "get_employees_logged_in_today", companySlug)
    // Parse and pass to template
}
```

**Admin Handler:**
```go
// Always get employees with timestamps
cmd := exec.Command("./venv/bin/python", "face_verify_db.py", 
    "get_employees_logged_in_today_with_times", companySlug)
// Parse and pass to template
```

### Template Display

```html
{{if .LoggedInToday}}
<div>
    <h3>👥 Colleagues Logged In Today ({{len .LoggedInToday}})</h3>
    {{range .LoggedInToday}}
        <div>{{.FirstName}} {{.LastName}}</div>
    {{end}}
</div>
{{end}}
```

## Use Cases

### Use Case 1: Team Coordination

**Scenario:** Employee needs to coordinate with team members

**Workflow:**
1. Employee logs in
2. Sees colleague list
3. Knows who's available today
4. Can plan meetings or collaboration

**Benefit:** Improved team coordination

### Use Case 2: New Employee Onboarding

**Scenario:** New hire wants to know the team

**Workflow:**
1. New employee logs in first time
2. Sees list of colleagues
3. Learns who's on the team
4. Feels welcomed and connected

**Benefit:** Better onboarding experience

### Use Case 3: Remote/Hybrid Work

**Scenario:** Hybrid team with varying schedules

**Workflow:**
1. Remote employee logs in
2. Sees who else is working today
3. Knows who's available for questions
4. Feels connected to team

**Benefit:** Reduced isolation in remote work

### Use Case 4: Shift Work

**Scenario:** Company with multiple shifts

**Workflow:**
1. Employee starts shift
2. Sees who's on same shift
3. Knows team composition for the day
4. Can coordinate shift handoffs

**Benefit:** Better shift coordination

## Limitations

### Current Implementation

- Shows all employees (no department filtering)
- 5-second delay for updates (polling, not WebSocket)
- No status indicators (active/idle/away)
- No profile pictures
- No contact information
- Requires JavaScript enabled

### What It Doesn't Do

❌ Display employee roles or departments
❌ Provide messaging or communication
❌ Show employee availability status (active/idle)
❌ Track employee location
❌ Show historical login patterns
❌ Push notifications for colleague logins

### What It DOES Do (Phase 5)

✅ Shows currently logged-in employees in real-time
✅ Auto-updates every 5 seconds without page refresh
✅ Removes employees immediately after logout
✅ Updates count dynamically
✅ Works for both employee and admin views

## Best Practices

### For Employees

- **Use for awareness** - Know who's working
- **Respect privacy** - Don't track or monitor others
- **Collaborate** - Reach out to colleagues
- **Stay professional** - Use information appropriately

### For Admins

- **Communicate purpose** - Explain feature to employees
- **Set expectations** - Clarify it's for collaboration
- **Monitor feedback** - Ensure employees comfortable
- **Respect concerns** - Address privacy questions

## Future Enhancements

1. ~~**Real-time updates**~~ - ✅ **COMPLETED in Phase 5** - Live list with 5-second refresh
2. **WebSocket support** - True push-based updates (no polling)
3. **Faster updates** - Sub-second refresh rates
4. **Department filtering** - Show only relevant colleagues
5. **Status indicators** - Available, busy, away, idle
6. **Profile pictures** - Visual identification
7. **Quick actions** - Message or call colleagues
8. **Team grouping** - Organize by department/role
9. **Custom visibility** - Opt-in/opt-out per employee
10. **Activity feed** - "John logged in 2 minutes ago"

## Troubleshooting

### No Colleagues Showing

**Possible Causes:**
- You're the first to log in today
- No other employees have clocked in yet
- Database query issue

**Solution:**
- Wait for other employees to log in
- Check if other employees are working today

### Wrong Names Showing

**Possible Causes:**
- Names not updated in employee records
- Database sync issue

**Solution:**
- Contact HR to update employee records
- Verify employee data in admin panel

### List Too Long

**Possible Causes:**
- Large team (many employees)
- All employees logged in today

**Solution:**
- Scroll through list (max 200px height)
- Feature working as designed

## Command Line Usage

**Employee View:**
```bash
# Get employees logged in today (names only)
python face_verify_db.py get_employees_logged_in_today <company_slug>
```

**Example:**
```bash
python face_verify_db.py get_employees_logged_in_today acmecorp

# Output format: FirstName|LastName
Alice|Johnson
Bob|Smith
Carol|Williams
```

**Admin View:**
```bash
# Get employees with timestamps (admin)
python face_verify_db.py get_employees_logged_in_today_with_times <company_slug>
```

**Example:**
```bash
python face_verify_db.py get_employees_logged_in_today_with_times acmecorp

# Output format: FirstName|LastName|UserID|LoginTime
Alice|Johnson|AJ1456|09:15:23
Bob|Smith|BS1457|08:45:12
Carol|Williams|CW1458|10:02:45
```

## Related Documentation

- **CLOCK_SYSTEM.md** - Clock-in/out workflow
- **README.md** - Overall system architecture
- **EMPLOYEE_SELF_SERVICE.md** - Employee features