Attendance Tracking, Breaks, and Shift Management

The Attendance module is the operational heartbeat of the platform. Every working day begins with a check-in that opens a session and ends with a check-out that closes it, calculating worked minutes and automatically classifying the day. Managers gain real-time visibility through team views, and employees can request corrections when timestamps are wrong — all without leaving the dashboard.

Shift Configuration

The platform ships with a single standard shift definition. All comparisons between check-in/out times and shift boundaries use Asia/Karachi (PKT) as the reference timezone, even though every timestamp is stored in UTC.

Field	Value
Shift start	5:00 PM PKT
Shift end	2:00 AM PKT (next calendar day)
Duration	9 hours
Timezone	Asia/Karachi (UTC+5)

All dashboard views, reports, and duration labels must render times in PKT. Durations display as HH:mm (e.g., 08:45), not raw minutes. Internal UUIDs are never shown — use the employee’s full name and the shift name instead.

Work Modes

When an employee checks in, they declare one of two work modes:

Enum value	Meaning
`office`	Employee is physically present at the office
`wfh`	Employee is working from home

The work_mode field is recorded on the session and influences reporting filters — it does not change session classification or flag logic.

Check-In Flow

Employee triggers check-in

The employee selects a work mode and submits the request. The system captures check_in_at at the precise instant the request is processed.

Active-session guard

If the employee already has a session in status active, the API rejects the request. Only one active session is permitted per user at any time.

Session created

A new AttendanceSession record is written with session_status = active. The is_late_login flag is set to true if check_in_at (in PKT) is after 5:00 PM.

Example Check-In Request

POST /api/v1/attendance/check-in
Authorization: Bearer <token>
Content-Type: application/json

{
  "work_mode": "office"
}

Check-In Response Fields (selected)

UUID

Unique session identifier (internal use only — not displayed in the UI).

user_full_name

string

Human-readable name of the employee shown in all views.

work_mode

string

office or wfh as declared at check-in time.

session_status

string

active, completed, incomplete, or corrected.

true when check-in occurred after the shift start time in PKT.

expected_shift_start_at

datetime (UTC ISO-8601)

The expected start boundary for this session’s shift, returned in UTC.

Check-Out Flow

Employee triggers check-out

The employee submits the check-out request. An optional body can carry early_checkout_reason or after-shift justification fields.

Metrics calculated

check_out_at is recorded. The system computes worked_minutes, duration_minutes, and total_hours. The is_early_logout flag is set if check-out is before 2:00 AM PKT.

Breaks auto-closed

Any break with status active at the time of check-out is automatically closed with ended_at = check_out_at.

Session classified

The system assigns an attendance_classification based on the rules in the table below, and sets session_status = completed.

If an employee is checking out after the shift end (e.g., past 2:00 AM PKT), the checkout_after_shift_reason and checkout_after_shift_note fields should be supplied in the request body to provide an audit trail.

Checkout Request Body (optional fields)

checkout_after_shift_reason

string | null

Short reason code for post-shift checkout (e.g., overtime, forgot_checkout).

checkout_after_shift_note

string | null

Free-text note elaborating on why the session ran past shift end.

early_checkout_reason

string | null

Reason when checking out before the shift end time.

Session Classification

After checkout the platform automatically assigns one of the following classifications to every session.

`attendance_classification`	Rule
`active`	Session is still open; employee has not checked out yet
`full_day`	`worked_minutes` ≥ 540 (9 hours)
`half_day`	`worked_minutes` ≥ 270 and < 540 (4.5 – 9 hours)
`short_leave`	`worked_minutes` < 270 (under 4.5 hours)
`insufficient`	Duration recorded but falls below the half-day threshold
`full_leave` / `leave`	No check-in, but an approved leave record covers the day

Operational Flags

Flag	Condition
`is_late_login`	Check-in after shift start (5 PM PKT)
`is_early_logout`	Check-out before shift end (2 AM PKT)
`is_overtime`	Session duration significantly exceeds 9 hours
`is_corrected`	Session was updated via an approved correction request

Break Tracking

Employees can log mid-session breaks without losing credit for paid work time. All breaks are classified as paid — break duration is not deducted from worked_minutes.

Break Types

`break_type`	Description
`dinner`	Standard meal break
`prayer`	Daily prayer time
`other`	Coffee, rest, or any miscellaneous short break

Break Rules

A break can only be started while an active attendance session exists.
Only one active break is allowed at a time. Starting a second break while one is open is rejected.
If the employee checks out while a break is still active, the system sets ended_at = check_out_at automatically.
Break durations are stored on the session in dedicated columns: dinner_break_minutes, prayer_break_minutes, and other_break_minutes.

Break Endpoints

Start Break
End Break
Current Break
Session Breaks

POST /api/v1/attendance/breaks/start
Authorization: Bearer <token>
Content-Type: application/json

{
  "break_type": "dinner",
  "note": "Heading to the cafeteria"
}

POST /api/v1/attendance/breaks/end
Authorization: Bearer <token>

GET /api/v1/attendance/breaks/current
Authorization: Bearer <token>

GET /api/v1/attendance/sessions/{session_id}/breaks
Authorization: Bearer <token>

Break Response Fields

break_type

string

dinner, prayer, or other.

started_at

datetime (UTC ISO-8601)

Timestamp when the break began.

ended_at

datetime | null

Timestamp when the break ended. null if the break is still active.

duration_minutes

integer | null

Calculated on break completion. null while the break is in progress.

is_paid

boolean

Always true — all recorded breaks count as paid time.

Auto-Close and Incomplete Sessions

If a session remains in active status for more than 24 hours, the system automatically marks it as incomplete and raises an alert. This safeguard handles forgotten checkouts and prevents stale active sessions from corrupting daily metrics.

The incomplete status signals that the session could not be classified normally and requires either a manual correction or manager intervention.

Attendance Correction Flow

Employees occasionally forget to check out or check in with the wrong timestamp. The correction workflow provides a structured, auditable remedy.

Employee submits correction request

PATCH /api/v1/attendance/{session_id}/correction-request with requested_check_in_at, requested_check_out_at, and a mandatory reason. The session flag correction_requested is set to true.

Manager reviews pending corrections

GET /api/v1/attendance/corrections/pending returns all sessions in the manager’s team scope that have pending correction requests.

Manager resolves the correction

PATCH /api/v1/attendance/{session_id}/resolve-correction with an action of approve, reject, or clarify. On approval, the system applies the corrected timestamps and recalculates all metrics from scratch.

Session updated

The session is_corrected flag is set to true and session_status transitions to corrected.

Correction Request Fields

requested_check_in_at

datetime | null

The corrected check-in timestamp the employee is requesting (UTC).

requested_check_out_at

datetime | null

The corrected check-out timestamp the employee is requesting (UTC).

reason

string

required

Mandatory human-readable explanation for the correction.

Correction Resolve Fields

action

string

required

One of approve, reject, or clarify.

check_in_at

datetime | null

Manager-confirmed corrected check-in (may differ from the employee’s request).

check_out_at

datetime | null

Manager-confirmed corrected check-out.

manager_comment

string | null

Optional comment explaining the decision.

Role-Based Access Summary

Endpoint	Employee	Manager / Team Lead	Admin / HR Ops
`POST /check-in`	✅ Own session	✅	✅
`POST /check-out`	✅ Own session	✅	✅
`GET /me`	✅ Own history	✅	✅
`GET /team`	❌	✅ Team scope	✅ All
`PATCH /{id}/correction-request`	✅ Own session	✅	✅
`GET /corrections/pending`	❌	✅ Team scope	✅ All
`PATCH /{id}/resolve-correction`	❌	✅ Team scope	✅ All

Overnight Session Handling

The standard shift crosses midnight: it starts at 5:00 PM on day N and ends at 2:00 AM on day N+1. The system correctly attributes a 1:30 AM check-out to the session that opened at 5:00 PM the previous calendar day, so daily summaries are never split across two date buckets incorrectly.

Get Started

Core Concepts

Features

Deployment

Shift Configuration

Work Modes

Check-In Flow

Example Check-In Request

Check-In Response Fields (selected)

Check-Out Flow

Checkout Request Body (optional fields)

Session Classification

Operational Flags

Break Tracking

Break Types

Break Rules

Break Endpoints

Break Response Fields

Auto-Close and Incomplete Sessions

Attendance Correction Flow

Correction Request Fields

Correction Resolve Fields

Role-Based Access Summary

Overnight Session Handling

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Deployment

Documentation Index

​Shift Configuration

​Work Modes

​Check-In Flow

​Example Check-In Request

​Check-In Response Fields (selected)

​Check-Out Flow

​Checkout Request Body (optional fields)

​Session Classification

​Operational Flags

​Break Tracking

​Break Types

​Break Rules

​Break Endpoints

​Break Response Fields

​Auto-Close and Incomplete Sessions

​Attendance Correction Flow

​Correction Request Fields

​Correction Resolve Fields

​Role-Based Access Summary

​Overnight Session Handling

Build docs developers (and LLMs) love

Shift Configuration

Work Modes

Check-In Flow

Example Check-In Request

Check-In Response Fields (selected)

Check-Out Flow

Checkout Request Body (optional fields)

Session Classification

Operational Flags

Break Tracking

Break Types

Break Rules

Break Endpoints

Break Response Fields

Auto-Close and Incomplete Sessions

Attendance Correction Flow

Correction Request Fields

Correction Resolve Fields

Role-Based Access Summary

Overnight Session Handling