👥 Workforce & Attendance Engineering Guide

This guide details the technical execution paths for user management (/employees), profile detail hubs (/employees/detail), live attendance monitoring (/attendance), and GPS location calculations.

---

👥 1. User Management Architecture (/employees)

The workforce management module is driven by components/employees/ components and custom hooks.

Data Fetching & Hooks (hooks/https/employees.ts)

• useGetEmployees(statusFilter, searchQuery, page): Fetches paginated staff list from /organization/employees.
• useCreateEmployee(): Dispatches single staff onboarding requests.
• useBulkUploadEmployees(): Validates and posts multipart CSV user data.

---

Bulk CSV Upload Parser Flow (bulk-upload-modal.tsx)

When administrators upload bulk workforce files, client-side validation parses CSV fields before submission:

// Required CSV Headers Validation
const REQUIRED_HEADERS = ["first_name", "last_name", "email", "employment_type"];

export function validateCsvHeaders(headers: string[]) {
  const missing = REQUIRED_HEADERS.filter((h) => !headers.includes(h));
  return {
    isValid: missing.length === 0,
    missingHeaders: missing,
  };
}

---

🕒 2. Attendance Logging & Geofencing (/attendance)

Attendance monitoring compiles live clock-in events, GPS coordinates, punctuality metrics, and excuse notes.

Geofence GPS Verification Algorithm (Haversine Formula)

When a user clocks in via mobile device, Work Clock HQ cross-references their mobile GPS coordinates (lat1, lon1) against the assigned office location coordinates (lat2, lon2) using the Haversine Formula to measure spherical distance in meters:

export function calculateDistanceMeters(
  lat1: number,
  lon1: number,
  lat2: number,
  lon2: number
): number {
  const R = 6371e3; // Earth's radius in meters
  const rad = Math.PI / 180;
  const dLat = (lat2 - lat1) * rad;
  const dLon = (lon2 - lon1) * rad;

  const a =
    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
    Math.cos(lat1 * rad) * Math.cos(lat2 * rad) *
    Math.sin(dLon / 2) * Math.sin(dLon / 2);

  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
  return R * c; // Distance in meters
}

• Verification Check: If Distance > Geofence Radius, the attendance record is flagged with a yellow/red location warning badge.

---

🗺️ 3. Google Maps Integration (components/ui/location-map.tsx)

Office locations rendering interactive Google Maps previews utilize the Google Maps JavaScript API overlay service:

import { GoogleMap, Marker, Circle, useJsApiLoader } from "@react-google-maps/api";

export function LocationMapPreview({ lat, lng, radiusMeters }: { lat: number; lng: number; radiusMeters: number }) {
  const { isLoaded } = useJsApiLoader({
    googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY || "",
  });

  if (!isLoaded) return <div>Loading Map...</div>;

  const center = { lat, lng };

  return (
    <GoogleMap mapContainerClassName="w-full h-64 rounded-xl" center={center} zoom={16}>
      <Marker position={center} />
      <Circle
        center={center}
        radius={radiusMeters}
        options={{
          fillColor: "#02144D",
          fillOpacity: 0.15,
          strokeColor: "#02144D",
          strokeWeight: 2,
        }}
      />
    </GoogleMap>
  );
}