Analytics & Reporting Engine

The TitanGrid backend features an aggressive, background-scheduled arithmetic engine. Because biometric hardware only provides raw timestamps (e.g., 08:14:00), the Reporting Engine is responsible for translating those raw punches into actionable human resource metrics.

The Arithmetic Processing Pipeline

The core matrix does not calculate metrics on-the-fly when a user requests a web page. Instead, a daemonized background process calculates shifts as punches arrive, ensuring instantaneous API responses even for multi-year organizational queries.

1. Grace Period Resolution

Every department in the system can be assigned a custom Grace Period integer (e.g., 15 minutes). If an employee is scheduled for 08:00 and clocks in at 08:14, the engine checks the threshold. Because 14 <= 15, the punch is flagged as on_time. If the punch is 08:16, the engine calculates a total variance of 16 late minutes.

2. Midnight Shift Crossings

Night shifts pose a unique mathematical challenge in time-and-attendance logic. If a security guard clocks in at 22:00 on Tuesday and clocks out at 06:00 on Wednesday, the engine must group these punches into a single logical "Tuesday Night Shift" rather than treating Wednesday as an incomplete day.

TitanGrid resolves this by checking the employee's assigned Shift Template. If the shift bridges midnight, the system artificially anchors the checkout time to the work_date of the previous calendar day.

Reporting Endpoints

When the Next.js frontend requests a daily summary, the backend aggregates the pre-calculated AttendanceRecord tables and serves a lightweight JSON matrix.

Operation Details

• Endpoint: GET /api/analytics/daily-summary/
• Action: Aggregates departmental metrics, calculates total expected headcount versus actual headcount, and returns an array of "flagged personnel" (employees who breached the grace period rules) for immediate HR intervention.

GET /api/analytics/daily-summary/

Params:
- target_date: "2026-06-07"
- department_filter: "Engineering"
- include_variances: true

{
  "meta": {
    "generated_at": "2026-06-07T09:05:00Z",
    "headcount_expected": 45,
    "headcount_actual": 42
  },
  "metrics": {
    "on_time": 38,
    "late": 4,
    "absent": 3,
    "total_late_minutes": 85
  },
  "flagged_personnel": [
    {
      "employee_code": "EMP-9042",
      "status": "late",
      "variance_str": "+14m",
      "punch_time": "08:14:00"
    }
  ]
}