Skip to main content

Functional Requirements

3.1 Organization Management​

Owner: SystemAdmin

  • Create, update, deactivate organizations.
  • Create, update, deactivate organization units under an organization.
  • Configure geo-location settings per unit (centre lat/lon, radius metres).
  • Configure attendance policy overrides per unit (grace minutes, red-flag actions).

3.2 Employee Management​

Owner: HR

  • Register new employee with basic PII and employment metadata.
  • Assign employee to one or more (org, unit) tuples.
  • Set category: permanent, intern, consultant, locum.
  • Activate / deactivate employee.
  • Handle permanent transfer between units with history preservation.

3.3 Shift Management​

Owner: SystemAdmin / OrgAdmin

  • Create shift: start_time, end_time, overnight flag.
  • Multiple shifts per day allowed; overlapping shifts for a unit are rejected.
  • Assign shifts to organization units.

3.4 Roster Management​

Owner: ShiftManager

  • Build monthly roster by assigning employees to shifts.
  • Slot locum replacements for covered shifts.
  • Modify roster mid-month; changes propagate and trigger recalculation where applicable.

3.5 Attendance Capture​

Channels: Mobile App, Web, Telegram.

3.5.1 Check-in Rules​

  • Earliest check-in allowed: 30 minutes before shift start.
  • Latest check-in allowed: 15 minutes after shift start (late, flagged).

3.5.2 Check-out Rules​

  • Earliest check-out allowed: 15 minutes before shift end (early, flagged).
  • Latest check-out allowed: 30 minutes after shift end.

3.5.3 Constraints​

  • No shift assigned to the employee on that date → check-in rejected.
  • Multiple punches are stored and flagged (MULTIPLE_PUNCHES).
  • Check-out without a preceding check-in is allowed but flagged (MISSING_CHECK_IN).
  • Overnight shifts are supported; the shift start date is treated as the attendance date.

3.6 Geo-Fencing​

  • Each unit can enable/disable geo-fencing.
  • Radius is configurable per unit.
  • Out-of-fence punches are flagged (GEO_VIOLATION). Enforcement can be allow + flag, block, or allow + require approval.

3.7 Device Binding​

  • Each employee can register devices.
  • New devices require HR approval before attendance is allowed.
  • Punches from unapproved devices are flagged DEVICE_MISMATCH and subject to policy.

3.8 Telegram Integration​

  1. Employee logs in to Telegram bot with employee_id + password.
  2. Telegram chat ID is linked to the employee record.
  3. HR approves the Telegram binding.
  4. Post-approval, the employee can check in/out via /in and /out commands.

3.9 Red Flag System​

Configurable violations:

  • LATE_CHECK_IN
  • EARLY_CHECK_OUT
  • GEO_VIOLATION
  • MULTIPLE_PUNCHES
  • MISSING_CHECK_OUT
  • MISSING_CHECK_IN
  • DEVICE_MISMATCH
  • SHIFT_WINDOW_VIOLATION

Actions per flag: allow + flag, block, allow + require approval.

3.10 Leave Management​

  • Employee submits a leave request.
  • Approval flow: ShiftManager → HR → SuperAdmin (override).
  • Approved leave blocks attendance rules for the affected dates.

3.11 Regularization​

  • Employee raises a correction request (missing punch, wrong check-in, etc.).
  • Same approval flow as leave.
  • Approval triggers attendance recalculation for the affected date(s).

3.12 Locum / Replacement​

  • Employee can suggest a replacement.
  • ShiftManager approves and assigns the locum.
  • Locum's attendance is tracked separately against the same shift slot.

3.13 Attendance Processing​

  1. Capture raw punches.
  2. For each (employee, shift date), identify first check-in and last check-out.
  3. Apply rules and compute status (Present, Absent, HalfDay, Leave, Holiday).
  4. Generate the attendance record.
  5. Attach flags.

3.14 Attendance Recalculation​

Triggered when:

  • Regularization is approved.
  • Shift assignment is changed.
  • Locum is assigned or revoked.
  • Attendance record is manually edited by an authorized user.

3.15 Attendance Locking​

  • Auto-lock on the 5th of the next month, OR manual lock by HR.
  • Post-lock, only SuperAdmin can modify; every change is audited.

3.16 Reporting​

Filters: organization, unit, employee, date range, shift, status, red flag.

Outputs: CSV, Excel (XLSX), PDF.

3.17 API Integration​

Public REST surface for downstream systems (payroll, billing) authenticated with Sanctum tokens. Example response:

{
  "employee_id": "E123",
  "date": "2026-04-01",
  "status": "Present",
  "check_in": "09:05",
  "check_out": "17:55",
  "flags": ["LATE_CHECK_IN"]
}