Axion/TIMECLOCK.md

Time Clock Page

A public-facing time clock interface for employees to sign in and out of their shifts.

Features

• Public Access: No login required to view the page
• Password-Only Authentication: Employees only need their password to clock in/out
• Visual Time Bars: Each employee has a time bar showing 8 AM - 6 PM
• Real-Time Status:
  • Red bar = Clocked out
  • Green bar = Clocked in
  • Yellow bar = On break
• Schedule Integration: Shows scheduled shift times and detects late arrivals/early departures
• Auto-Refresh: Status updates every 30 seconds
• Timecard Integration: Automatically creates/updates timecard entries

Access

Navigate to: http://localhost:5173/timeclock

Usage

1. View Status: All employees are displayed in a grid with their current status
2. Clock In/Out: Click on an employee's name
3. Enter Password: Enter the employee's password (not email)
4. Confirm: Click "Clock In" or "Clock Out" button

Time Bar Visualization

• Background: Gray grid showing hourly markers (8:00 AM - 6:00 PM)
• Scheduled Time: Light blue overlay showing scheduled shift times
• Current Status: Colored bar (red/green/yellow) showing clock status
• Current Time Indicator: Black vertical line showing current time
• Late Indicator: Red marker if employee arrived late

API Endpoints

GET /api/timeclock/status

Returns all employees with their current clock status.

No authentication required

Response:

[
  {
    "id": "1",
    "name": "John Doe",
    "email": "employee@company.com",
    "currentStatus": "clocked_in",
    "clockInTime": "08:15",
    "scheduledStart": "08:00",
    "scheduledEnd": "17:00",
    "isLate": true,
    "leftEarly": false
  }
]

POST /api/timeclock/action

Clock in/out action with password authentication.

No authentication required

Request:

{
  "employeeId": "1",
  "password": "employee123",
  "action": "clock_in"
}

Actions:

• clock_in - Clock in for the day
• clock_out - Clock out for the day
• break_start - Start break
• break_end - End break

Integration

With Schedule

• Automatically checks if employee has a scheduled shift for today
• Compares clock in time with scheduled start time
• Marks timecard as "Late arrival" if clocked in after scheduled time
• Marks timecard as "Left early" if clocked out before scheduled end time

With Timecards

• Automatically creates a timecard entry when employee clocks in
• Updates timecard with clock out time
• Calculates total hours and overtime
• Deducts break time from total hours

Security

• Password verification using bcrypt
• No JWT tokens required for viewing
• Only password needed for clock actions
• All actions are logged in timecards table

Customization

Change Time Range

Edit the time bar range in TimeClock.tsx:

const startMinutes = 8 * 60; // 8:00 AM
const endMinutes = 18 * 60; // 6:00 PM

Change Refresh Interval

Modify the interval in TimeClock.tsx:

const interval = setInterval(fetchEmployees, 30000); // 30 seconds

Change Colors

Modify the status colors:

const getStatusColor = (employee: EmployeeStatus): string => {
  if (employee.currentStatus === 'clocked_in') return 'bg-green-500';
  if (employee.currentStatus === 'on_break') return 'bg-yellow-500';
  return 'bg-red-500';
};