# Face Attendance App – API Documentation

## Overview
This system provides:
- Username & password authentication
- First-time face enrollment with approval workflow
- Face-based Check-In / Check-Out
- Mandatory location verification
- Centralized user & attendance status management
- Attendance history with pagination and search
- User profile
- Secure logout with refresh token support

All face verification and liveness detection are handled on the backend.

---

## Core Design Principle

`GET /api/attendance/status` is the **single source of truth** for:
- User approval state
- Attendance state
- Allowed actions in the mobile app

Flutter must rely on this endpoint to decide **what the user can do next**.

---

## Authentication Flow

1. User logs in using username & password
2. Backend returns access token and refresh token
3. App navigates to Home
4. App calls `/api/attendance/status`
5. Backend determines:
- User approval status
- Attendance status for today
6. App updates UI accordingly

---

## Authentication Endpoints

### Login
POST /api/auth/login

Request:

{
  "username": "employee01",
  "password": "********",
  "latitude": 1.2323,
  "longitude": 1.3434
}

Response:

{
  "success": true,
  "access_token": "jwt_access_token",
  "refresh_token": "jwt_refresh_token",
  "is_first_login": true,  
  "user": {
    "id": 12,
    "name": "Ahmed Ali",
    "username": "employee01",
    "email": "[e-mail]"
  }
}

---

### Refresh Token
POST /api/auth/refresh

Request:

{
  "refresh_token": "jwt_refresh_token"
}

Response:

{
  "success": true,
  "access_token": "new_jwt_access_token"
}

---

### Logout
POST /api/auth/logout

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

---

## Face Management

### Face Enrollment (First Login Only)
POST /api/face/enroll

Headers:
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

Request fields:
- image: file (jpg/png)
- device: ios / android
- deviceId: string

Response:

{
  "success": true,
  "message": "Face enrolled successfully"
}

> After enrollment, the user status becomes `pending`
> Approval is handled administratively on the backend.

---

## Attendance Status (Centralized Status Endpoint)

### Get Current Status
GET /api/attendance/status

Headers:
Authorization: Bearer <access_token>

### Response (General Structure)

{
  "success": true,
  "user_status": "active",
  "attendance_status": "checked_in",
  "date": "2026-01-15",
  "check_in_time": "09:02",
  "check_out_time": null
}

---

### User Status Values

| user_status | Meaning | App Behavior |
|---|---|---|
| `pending` | Face enrolled, waiting for approval | Show “Waiting for Approval” |
| `active` | User approved | Allow Check-In / Check-Out |
| `blocked` | User blocked | Disable all attendance actions |

---

### Attendance Status Values

| attendance_status | Meaning | App Behavior |
|---|---|---|
| `not_checked_in` | No action done today | Show Check-In |
| `checked_in` | Check-In completed | Show Check-Out |
| `checked_out` | Day completed | Show Attendance Completed |
| `not_allowed` | Action blocked by system | Show error message |

---

## Attendance Actions

### Check-In
POST /api/attendance/check-in

Headers:
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

Request fields:
- image: file (required)
- device: ios / android (required)
- deviceId: string (required)
- latitude: number (required)
- longitude: number (required)

Response:

{
  "success": true,
  "verified": true,
  "liveness": true,
  "check_in_time": "2026-01-15T09:02:00",
  "within_allowed_time": true
}

---

### Check-Out
POST /api/attendance/check-out

Request fields:
- image: file (required)
- device: ios / android (required)
- deviceId: string (required)
- latitude: number (required)
- longitude: number (required)

Response:

{
  "success": true,
  "verified": true,
  "liveness": true,
  "check_out_time": "2026-01-15T17:01:00",
  "within_allowed_time": false
}

---

## Attendance History (Pagination + Search)

GET /api/attendance/history

Query Params:

?page=1
&limit=20
&from=2026-01-01
&to=2026-01-31

Response:

{
  "success": true,
  "page": 1,
  "limit": 20,
  "total": 120,
  "records": [
    {
      "date": "2026-01-15",
      "check_in": "09:02",
      "check_out": "17:01",
      "within_allowed_time": true
    }
  ]
}

---

## User Profile

GET /api/user/profile

Response:

{
  "success": true,
  "user": {
    "id": 12,
    "name": "Ahmed Ali",
    "username": "employee01",
    "email": "[e-mail]"
  }
}

---

## Security & Rules

- All endpoints except login and refresh require authorization
- Location (latitude & longitude) is mandatory for Check-In and Check-Out
- Only one face is allowed per image
- Each Check-In and Check-Out requires capturing a new live image
- Images are processed temporarily and deleted after verification
- Backend is the single source of truth for all decisions

---

## Notes

### Flutter Responsibilities
- Open front camera with live preview
- Capture image with user interaction
- Basic client-side validation:
- One face only
- Eyes open
- Acceptable face orientation
- Collect device location
- Send image + location to backend
- Delete image locally after upload

### Backend Responsibilities
- User approval workflow
- Liveness detection (anti-spoofing)
- Face matching and confidence calculation
- Location validation (geofencing if required)
- Working-time validation
- Final attendance decision and persistence

---

## Application Flowchart

flowchart TD
    A[App Launch] --> B{Token Exists?}

    B -- No --> C[Login Screen]
    B -- Yes --> D[Refresh / Validate Token]

    C --> E[POST /auth/login]
    E --> H[Home Screen]

    H --> S[GET /attendance/status]

    S --> US{user_status}

    US -- first_login --> ENROLL[Face Enrollment]
    ENROLL --> CAM1[Open Camera]
    CAM1 --> CAP1[Capture Face]
    CAP1 --> SEND1[POST /face/enroll]
    SEND1 --> PEND[Status = pending]
    PEND --> WAIT[Waiting for Approval]
    WAIT --> S

    US -- pending --> WAIT
    US -- blocked --> BLOCKED[Access Denied]

    US -- active --> AS{attendance_status}

    AS -- not_checked_in --> CI_BTN[Show Check-In]
    AS -- checked_in --> CO_BTN[Show Check-Out]
    AS -- checked_out --> DONE[Attendance Completed]

    CI_BTN --> CI_FLOW[Check-In Flow]
    CO_BTN --> CO_FLOW[Check-Out Flow]

    CI_FLOW --> CAM2[Open Camera]
    CO_FLOW --> CAM2

    CAM2 --> CAP2[Capture Photo]
    CAP2 --> VALID[Validate Face + Eyes]
    VALID --> LOC[Get Location]
    LOC --> SEND2[Send Image + Location]
    SEND2 --> DEL[Delete Local Image]

    SEND2 --> CI[POST /attendance/check-in]
    SEND2 --> CO[POST /attendance/check-out]

    CI --> H
    CO --> H

    H --> HISTORY[Attendance History]
    H --> PROFILE[User Profile]
    H --> LOGOUT[Logout]

    LOGOUT --> LO[POST /auth/logout]
    LO --> C