Timesheet Management

Timesheet provides comprehensive time tracking capabilities with modern features like face detection, geofencing, offline support, and detailed reporting. The system is designed for Australian businesses with award compliance and penalty rate calculations.

Overview

The timesheet system handles all aspects of time tracking:

• Clock Interface - Modern PIN-based clock-in/out with photo capture
• Time Tracking - Automatic calculation of work hours and breaks
• Geofencing - Location-based restrictions and verification
• Offline Mode - Works without internet connection with automatic sync
• Break Management - Automatic break rules and manual break tracking
• Reporting - Comprehensive timesheet reports and analytics

Key Features

Modern Clock Interface

• PIN-based employee identification
• Face detection with photo capture
• Real-time camera feed with overlay information
• Geolocation verification and geofencing
• Offline capability with sync when online

Advanced Time Tracking

• Automatic work hour calculations
• Break time tracking with paid/unpaid rules
• Overtime detection and penalty rate application
• Shift matching with roster schedules
• Time rounding and validation rules

Australian Compliance

• Modern award integration
• Penalty rate calculations (overtime, weekends, public holidays)
• Break rule enforcement based on hours worked
• Leave integration (annual leave, sick leave, TOIL)
• Audit trail for compliance reporting

Clock Interface

PIN Entry System

The clock interface uses a secure PIN system:

1. PIN Entry - Employees enter their unique 4-digit PIN
2. Employee Verification - System validates PIN and loads employee data
3. Location Check - Verifies employee is at correct location (if geofencing enabled)
4. Photo Capture - Optional face detection and photo capture
5. Time Recording - Records clock-in/out with timestamp and location

Clock Interface Features

Real-Time Information Display

• Current time and date
• Employee name and role
• Current location (detected or offline mode)
• Last clock status (clocked in, on break, clocked out)
• Today's punch times (in, break, out)

Face Detection Integration

• Automatic face detection using browser APIs
• Photo capture for security and identification
• Face status indicators (ready, too far, no face detected)
• Optional feature - can be disabled per location

Geofencing Support

• GPS location verification
• Configurable radius per location (50-200 metres)
• Soft mode (warning) or hard mode (blocking)
• Offline mode when GPS unavailable

Clock Actions

Available Actions

Action Flow

graph TD
    A[Not Clocked In] --> B[Clock In]
    B --> C[Working]
    C --> D[Start Break]
    D --> E[On Break]
    E --> F[End Break]
    F --> C
    C --> G[Clock Out]
    G --> A

Timesheet Data Structure

Core Timesheet Fields

Break Tracking Fields

Daily Shift Aggregation

The system automatically aggregates timesheet entries into daily shifts:

interface IDailyShift {
  pin: string
  date: Date
  clockIn?: {
    time: string
    image?: string
    lat?: string
    lng?: string
    deviceId?: string
    deviceLocation?: string
  }
  breakIn?: {
    time: string
    deviceId?: string
    deviceLocation?: string
  }
  breakOut?: {
    time: string
    deviceId?: string
    deviceLocation?: string
  }
  clockOut?: {
    time: string
    image?: string
    lat?: string
    lng?: string
    deviceId?: string
    deviceLocation?: string
  }
  totalWorkingHours: number
  totalBreakMinutes: number
  scheduleShiftId?: ObjectId
}

Break Management

Automatic Break Rules

Break rules are configured per award and employment type:

interface IBreakRule {
  label: string           // "Unpaid meal break"
  minHours: number       // Minimum hours to trigger break
  maxHours: number | null // Maximum hours (null = no limit)
  breakMinutes: number   // Break duration in minutes
  paid: boolean          // Whether break is paid
}

Break Rule Examples

Break Enforcement

• Automatic Detection - System detects when breaks are required
• Reminder Notifications - Alerts when break is due
• Compliance Tracking - Records break compliance for auditing
• Manual Override - Managers can adjust break times if needed

Geofencing System

Location Configuration

Each location can have geofencing configured:

interface ILocationGeofence {
  lat: number              // Centre latitude
  lng: number              // Centre longitude  
  radius: number           // Radius in metres
  geofenceMode: "soft" | "hard"  // Enforcement mode
  address: string          // Physical address
  openingHour?: number     // Opening time (0-23)
  closingHour?: number     // Closing time (0-24)
  workingDays?: number[]   // Working days (0=Sunday)
}

Geofence Modes

Soft Mode (Recommended)

• Allows clock-in outside geofence
• Shows warning message to employee
• Flags entry for manager review
• Useful for flexible work arrangements

Hard Mode (Strict)

• Blocks clock-in outside geofence
• Shows error message with distance
• Requires employee to move closer
• Useful for security-sensitive locations

Location Detection

The system detects employee location using:

1. GPS Coordinates - Browser geolocation API
2. Distance Calculation - Haversine formula for accuracy
3. Fallback Handling - Offline mode when GPS unavailable
4. Manual Override - Admin can override location restrictions

Offline Mode

Offline Capabilities

Timesheet works fully offline with these features:

• Clock-in/out without internet connection
• Local storage of timesheet entries
• Photo capture and local storage
• Automatic sync when connection returns
• Offline status indicators

Sync Process

graph TD
    A[Offline Entry] --> B[Store Locally]
    B --> C[Connection Available?]
    C -->|No| D[Stay in Queue]
    C -->|Yes| E[Upload to Server]
    E --> F[Verify Upload]
    F -->|Success| G[Remove from Queue]
    F -->|Failed| H[Retry Later]
    H --> C

Offline Data Management

• Local Storage - IndexedDB for timesheet entries
• Photo Storage - Base64 encoding for offline photos
• Queue Management - Automatic retry with exponential backoff
• Conflict Resolution - Server-side duplicate detection
• Status Indicators - Clear offline/online status display

API Endpoints

Timesheet Management

Get Timesheets

GET /api/timesheets?startDate=2024-01-01&endDate=2024-01-31&employeeId=123

Query Parameters:

• startDate - Start date (YYYY-MM-DD)
• endDate - End date (YYYY-MM-DD)
• employeeId - Filter by employee ID(s)
• employer - Filter by employer name(s)
• location - Filter by location name(s)
• role - Filter by role name(s)
• limit - Results per page (default: 50)
• offset - Pagination offset
• sortBy - Sort field: date, name, totalHours
• order - Sort order: asc, desc

Response:

{
  "timesheets": [
    {
      "date": "01-01-2024",
      "employeeId": "employee_id",
      "name": "John Smith",
      "pin": "1001",
      "role": "Manager",
      "employer": "Main Company Pty Ltd",
      "location": "Head Office",
      "clockIn": "9:00 AM",
      "breakIn": "12:30 PM",
      "breakOut": "1:00 PM", 
      "clockOut": "5:30 PM",
      "breakMinutes": 30,
      "breakHours": "0h 30m",
      "totalMinutes": 480,
      "totalHours": "8h 0m",
      "clockInDeviceId": "device_123",
      "clockInDeviceLocation": "Head Office Kiosk"
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0,
  "totalWorkingMinutes": 12000,
  "totalBreakMinutes": 750,
  "totalWorkingHours": "200h 0m",
  "totalBreakHours": "12h 30m"
}

Create Timesheet Entry

POST /api/timesheets
Content-Type: application/json

{
  "pin": "1001",
  "type": "in",
  "date": "2024-01-15",
  "time": "09:00:00",
  "image": "cloudinary_url",
  "lat": "-37.8136",
  "lng": "144.9631",
  "where": "Head Office",
  "deviceId": "kiosk_001",
  "deviceLocation": "Head Office Entrance"
}

Clock Interface API

Employee Clock Status

GET /api/employee/me/clock-status

Response:

{
  "employee": {
    "id": "employee_id",
    "name": "John Smith",
    "pin": "1001",
    "role": "Manager",
    "detectedLocation": "Head Office"
  },
  "todayPunches": {
    "clockIn": "2024-01-15T09:00:00Z",
    "breakIn": "2024-01-15T12:30:00Z", 
    "breakOut": "2024-01-15T13:00:00Z",
    "clockOut": null
  },
  "currentStatus": "working",
  "isBirthday": false
}

Clock Action

POST /api/employee/clock
Content-Type: application/json

{
  "action": "in",
  "location": {
    "lat": -37.8136,
    "lng": 144.9631
  },
  "photo": "base64_image_data",
  "deviceId": "kiosk_001"
}

Reporting and Analytics

Dashboard Views

Day View

• Individual employee timesheets for selected date
• Detailed punch times and break information
• Photo thumbnails and location data
• Flagged entries and compliance issues

Week View

• Weekly summary for all employees
• Total hours and overtime calculations
• Break compliance tracking
• Shift pattern analysis

Month View

• Monthly aggregated data
• Payroll preparation reports
• Award compliance summaries
• Trend analysis and insights

Export Options

CSV Export

• Customisable field selection
• Date range filtering
• Employee/location/role filtering
• Formatted for payroll systems

PDF Reports

• Professional timesheet reports
• Company branding and logos
• Compliance statements
• Manager approval sections

Analytics Features

• Attendance Patterns - Late arrivals, early departures
• Overtime Analysis - Overtime trends and costs
• Break Compliance - Break rule adherence
• Location Usage - Popular work locations
• Device Analytics - Kiosk usage statistics

Common Use Cases

Daily Operations

1. Employee Clock-In

   • Employee enters PIN at kiosk or mobile device
   • System captures photo and location
   • Verifies geofencing compliance
   • Records start time

2. Break Management

   • System detects when break is due
   • Employee clocks out for break
   • Tracks break duration
   • Ensures compliance with award rules

3. End of Shift

   • Employee clocks out
   • System calculates total hours
   • Applies penalty rates if applicable
   • Generates daily shift summary

Management Tasks

1. Daily Monitoring

   • Review flagged entries
   • Check attendance patterns
   • Verify break compliance
   • Approve overtime

2. Weekly Reporting

   • Generate payroll reports
   • Review overtime costs
   • Check award compliance
   • Export data for payroll

3. Monthly Analysis

   • Analyse attendance trends
   • Review location usage
   • Calculate penalty rate costs
   • Generate compliance reports

Best Practices

Clock Interface Setup

• Position kiosks in well-lit areas for face detection
• Ensure stable internet connection for real-time sync
• Configure appropriate geofence radius (100-200m recommended)
• Test offline mode functionality regularly

Time Tracking Accuracy

• Use automatic break rules where possible
• Regular calibration of geofencing coordinates
• Monitor and address flagged entries promptly
• Maintain accurate employee role assignments

Compliance Management

• Regular review of award configurations
• Monitor break rule compliance
• Document any manual time adjustments
• Maintain audit trails for compliance reporting

Data Quality

• Regular backup of timesheet data
• Monitor sync queue for offline entries
• Validate GPS coordinates for accuracy
• Review and clean flagged entries

Troubleshooting

Common Issues

Clock-In Problems

• PIN Not Recognised: Verify PIN is correct and employee is active
• Location Issues: Check GPS permissions and geofence settings
• Photo Capture Fails: Verify camera permissions and lighting
• Offline Mode: Check local storage and sync queue

Time Calculation Issues

• Incorrect Hours: Verify time zone settings and date formats
• Break Calculations: Check break rules and award configuration
• Penalty Rates: Verify award assignments and penalty rule setup
• Overtime Issues: Check standard hours and overtime thresholds

Sync Problems

• Offline Entries Not Syncing: Check internet connection and server status
• Duplicate Entries: Review sync queue and server-side deduplication
• Photo Upload Failures: Verify Cloudinary configuration and file sizes
• Data Conflicts: Check for manual time adjustments and conflicts

Next Steps

• Clock Interface - Detailed clock-in/out interface guide
• Timesheet Data - Data structure and calculations
• Reporting - Advanced reporting and analytics
• Offline Mode - Offline functionality and sync