geolocation

# Geolocation Tracking Feature

## Overview

The geolocation tracking feature allows administrators to enable location tracking for employee clock-in and clock-out activities. GDPR compliance is handled at the employer level - the admin must consent when enabling the feature.

## Features

### 1. Admin Controls
- **Enable/Disable**: Administrators can turn geolocation tracking on or off
- **Employer GDPR Consent**: Admin must confirm lawful basis when enabling
- **Settings Integration**: Geolocation settings are part of the main company settings page

### 2. Employer Consent (GDPR)
When enabling geolocation, the admin must confirm:
- Company has a lawful basis for collecting employee location data
- Employees have been informed via employment contracts or privacy notices
- Location data will only be used for attendance verification
- Company will handle data subject access and deletion requests

### 3. Employee Experience
- **Automatic**: Location captured automatically when geolocation is enabled
- **Browser Permission**: Standard browser location permission prompt
- **Graceful Fallback**: Clock-in proceeds if location access is denied

### 4. Location Data
- **Coordinates**: Captures latitude and longitude during clock-in/out
- **Address Resolution**: Converts coordinates to human-readable addresses
- **Map Visualization**: Interactive maps showing employee locations using Folium

## Technical Implementation

### Database Schema

**Companies Table** (new columns):
```sql
geolocation_enabled BOOLEAN DEFAULT FALSE
```

**Employee Logs Tables** (new columns):
```sql
login_latitude DECIMAL(10, 8)
login_longitude DECIMAL(11, 8)
login_address TEXT
logout_latitude DECIMAL(10, 8)
logout_longitude DECIMAL(11, 8)
logout_address TEXT
```

### API Functions

**Python Backend Functions:**
- `get_geolocation_enabled(company_slug)` - Check if geolocation is enabled
- `update_geolocation_enabled(company_slug, enabled)` - Enable/disable geolocation
- `get_employees_with_locations(company_slug)` - Get current employees with locations
- `generate_location_map(company_slug)` - Create interactive map
- `reverse_geocode(latitude, longitude)` - Convert coordinates to address

**Go HTTP Handlers:**
- `checkGeolocationHandler` - Check if geolocation is enabled for login page
- Enhanced `dynamicLoginHandler` - Process location data during login
- Enhanced `dynamicSettingsHandler` - Manage geolocation settings

### Frontend Integration

**Login Flow:**
1. Employee clicks "Start Face Verification"
2. System checks if geolocation is enabled for company
3. If enabled, browser requests location permission
4. Employee can consent or continue without location
5. Face is matched against all registered employees
6. Location is captured and sent with verification

**JavaScript Functions:**
- `checkGeolocationAndStart()` - Check company geolocation settings
- `getCurrentLocation()` - Capture user location with consent
- `startCamera()` - Handle camera and location flow

## GDPR Compliance

### Data Collection
- **Explicit Consent**: Users must actively consent to location tracking
- **Purpose Limitation**: Location data used only for attendance verification
- **Transparency**: Clear information about data usage provided to users

### Data Rights
- **Access**: Employees can view their location data in logs
- **Deletion**: Location data can be deleted upon request
- **Portability**: Location data included in data export requests

### Privacy Safeguards
- **Minimal Data**: Only coordinates and address stored
- **Secure Storage**: Location data encrypted in database
- **Access Control**: Only authorized HR personnel can view locations

## Usage Instructions

### For Administrators

**Enable Geolocation:**
1. Go to Company Settings (`/<company>/settings`)
2. Scroll to "🌍 Geolocation Tracking" section
3. Select "Enabled" from dropdown
4. Click "Save All Settings"

**View Employee Locations:**
1. Go to Admin Dashboard (`/<company>/admin`)
2. In the "🌍 Employee Locations" section:
   - Click **"View Login Locations"** to see where employees logged in today
   - Click **"View Logout Locations"** to see where employees logged out today
   - Click **"View Interactive Map"** to see locations on a map

**Location Data Displayed:**
- Employee name
- Login/Logout time
- Address (street, suburb, city)

**Disable Geolocation:**
1. Go to Company Settings
2. Select "Disabled" from geolocation dropdown
3. Save settings (existing location data preserved)

### For Employees

**Clock-in with Location:**
1. Click "Start Face Verification" on login page
2. Browser will request location permission (if geolocation enabled)
3. Allow location access for tracking
4. Complete face verification as normal
5. Location is automatically captured

**Clock-out with Location:**
1. Click logout from the employee dashboard
2. Location is automatically captured at logout time

## API Endpoints

### Location APIs

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/<company>/api/login-locations` | GET | Today's login locations |
| `/<company>/api/logout-locations` | GET | Today's logout locations |
| `/<company>/api/location-map` | GET | Generate interactive map |

### Response Format

Login/Logout locations return pipe-delimited text:
```
USER_ID|FIRST_NAME|LAST_NAME|TIME|ADDRESS
EMP001|John|Doe|09:15:32|123 Main St, London
EMP002|Jane|Smith|09:22:45|456 High St, Manchester
```

## Python Functions

### Backend Functions

```python
# Get today's login locations
get_todays_login_locations(company_slug)

# Get today's logout locations  
get_todays_logout_locations(company_slug)

# Get currently logged-in employees with locations
get_employees_with_locations(company_slug)

# Generate interactive map
generate_location_map(company_slug)

# Convert coordinates to address
reverse_geocode(latitude, longitude)
```

## Map Visualization

### Interactive Maps
- **Technology**: Python Folium library generates HTML maps
- **Base Layers**: Street Map (OpenStreetMap), Satellite (Esri), Terrain (OpenTopoMap)
- **Filtering**: Toggle visibility of logged-in vs logged-out employees
- **Color Coding**: Blue markers = currently logged in, Gray markers = logged out

### Map Features
- **Layer Control**: Top-right panel to switch map styles and filter employees
- **Popup Details**: Click any marker to see:
  - Employee name and ID
  - Login time and login address
  - Logout time and logout address (if logged out)
  - Current status
- **Responsive**: Works on desktop and mobile browsers
- **Access**: Available to HR/admin through admin dashboard

### Map Generation
```python
# Generate map for currently logged-in employees
python face_verify_db.py generate_location_map <company_slug>
```

## Address Resolution

### Geocoding Service
- **Provider**: OpenStreetMap Nominatim (free, no API key required)
- **Data**: Converts coordinates to street address, town, city
- **Fallback**: Graceful handling if geocoding service unavailable
- **Privacy**: No data sent to third parties without consent

### Address Format
- Street number and name
- Suburb/neighborhood (if available)
- Town/village (if available)
- City/county

## Security Considerations

### Data Protection
- **Encryption**: Location data encrypted at rest
- **Access Control**: Only authorized personnel can access location data
- **Audit Trail**: All location data access logged

### Privacy by Design
- **Opt-in**: Location tracking disabled by default
- **Granular Control**: Per-company enable/disable
- **User Choice**: Employees can decline location sharing

## Database Schema

### Companies Table
```sql
geolocation_enabled BOOLEAN DEFAULT FALSE
```

### Employee Logs Table
```sql
login_latitude DOUBLE PRECISION
login_longitude DOUBLE PRECISION
login_address TEXT
logout_latitude DOUBLE PRECISION
logout_longitude DOUBLE PRECISION
logout_address TEXT
geolocation_consent BOOLEAN DEFAULT FALSE
```

## Error Handling

### Location Failures
- **GPS Unavailable**: System continues without location data
- **Permission Denied**: User can still log in without location
- **Network Issues**: Graceful fallback to coordinate-only storage

### Geocoding Failures
- **Service Unavailable**: Coordinates stored, address lookup retried later
- **Invalid Coordinates**: Error logged, login continues
- **Rate Limiting**: Implements respectful API usage patterns

### Integration Opportunities
- **Payroll Systems**: Export location data with timesheet reports
- **Security Systems**: Integration with building access controls
- **Mobile Apps**: Native mobile app with enhanced location features

## Compliance Notes

### GDPR Requirements Met
- ✅ **Lawful Basis**: Legitimate interest for workplace security
- ✅ **Consent**: Explicit opt-in consent mechanism
- ✅ **Transparency**: Clear privacy information provided
- ✅ **Data Minimization**: Only necessary location data collected
- ✅ **Purpose Limitation**: Data used only for stated purposes
- ✅ **Storage Limitation**: Data retention policies can be implemented
- ✅ **Security**: Appropriate technical safeguards in place
- ✅ **Accountability**: Documentation and audit trails maintained

### Regional Considerations
- **EU**: Full GDPR compliance implemented
- **US**: Meets state privacy law requirements
- **Other Regions**: Adaptable to local privacy regulations

This geolocation feature provides valuable attendance verification capabilities while maintaining the highest standards of privacy and data protection.