> ## Documentation Index
> Fetch the complete documentation index at: https://docs.criar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Attendance Management

> Comprehensive attendance tracking for students across Parent, Teacher, and Web Admin apps.

## 1. API Purpose

The Attendance API allows parents to monitor their child's daily presence and enables teachers/admins to record and update attendance records. It ensures transparency and accurate record-keeping for the school.

***

## 2. Endpoint Definition

| Method | Route                          | Auth   | Description                       |
| ------ | ------------------------------ | ------ | --------------------------------- |
| GET    | `/parent-app/attendance`       | 🔐 JWT | View student attendance history   |
| GET    | `/teachers-app/attendance`     | 🔐 JWT | View class/student attendance     |
| POST   | `/teachers-app/attendance`     | 🔐 JWT | Record student attendance         |
| PUT    | `/teachers-app/attendance/:id` | 🔐 JWT | Update specific attendance record |
| GET    | `/web-app/view-attendance`     | 🔐 JWT | Admin: attendance reports         |

***

## 3. Authentication Flow

1. **Token Validation:** Every request must include a Bearer JWT.
2. **Context Extraction:** The API extracts `skole_id` and `user_role` from the token.
3. **Data Scoping:**
   * Parents can only access records for their linked children (`student_id` check).
   * Teachers can only access records for assigned grades/students.
   * Admins have full read/write access within their `skole_id`.

***

## 4. Request Structure

#### GET /parent-app/attendance

**Query Parameters:**

| Field    | Type   | Required | Description                |
| -------- | ------ | -------- | -------------------------- |
| roll\_no | string | Yes      | Unique student identifier. |

**Headers:**

```http theme={null}
Authorization: Bearer <JWT_TOKEN>
```

#### GET /teachers-app/attendance

**Query Parameters:**

| Field       | Type   | Required | Description                  |
| ----------- | ------ | -------- | ---------------------------- |
| skole\_id   | string | Yes      | School identifier.           |
| student\_id | number | No       | Filter by specific student.  |
| date        | string | No       | Filter by date (YYYY-MM-DD). |
| grade       | string | No       | Filter by grade/class.       |

#### POST /teachers-app/attendance

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "student_id": 45,
  "attendance_status": "Present",
  "availability_status": "In",
  "date": "2024-03-16"
}
```

#### PUT /teachers-app/attendance/:id

**URL Parameters:**

| Field | Type   | Description                         |
| ----- | ------ | ----------------------------------- |
| id    | number | Unique ID of the attendance record. |

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "student_id": 45,
  "attendance_status": "Absent",
  "availability_status": "OUT",
  "date": "2024-03-16"
}
```

#### GET /web-app/view-attendance

**Query Parameters:**

| Field       | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| skole\_id   | string | Yes      | School identifier.        |
| start\_date | string | No       | Filter from (YYYY-MM-DD). |
| end\_date   | string | No       | Filter to (YYYY-MM-DD).   |
| grade       | string | No       | Filter by grade/class.    |

***

## 5. Response Structure

#### Success: Student Attendance History (200 OK)

**Route:** `GET /parent-app/attendance`

```json theme={null}
{
  "success": true,
  "message": "Attendance records retrieved",
  "data": [
    {
      "date": "2024-03-16",
      "attendance_status": "Present",
      "availability_status": "In"
    },
    {
      "date": "2024-03-15",
      "attendance_status": "Absent",
      "availability_status": "OUT"
    }
  ]
}
```

#### Success: Class Attendance View (200 OK)

**Route:** `GET /teachers-app/attendance`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "student_id": 45,
      "student_name": "Aarav Sharma",
      "attendance_status": "Present",
      "date": "2024-03-16"
    }
  ]
}
```

#### Success: Attendance Recorded (201 Created)

**Route:** `POST /teachers-app/attendance`

```json theme={null}
{
  "success": true,
  "message": "Attendance marked successfully",
  "data": {
    "id": 1024,
    "student_id": 45,
    "attendance_status": "Present",
    "date": "2024-03-16"
  }
}
```

#### Success: Attendance Updated (200 OK)

**Route:** `PUT /teachers-app/attendance/:id`

```json theme={null}
{
  "success": true,
  "message": "Attendance record updated",
  "data": {
    "id": 1024,
    "attendance_status": "Absent"
  }
}
```

#### Success: Attendance Report (200 OK)

**Route:** `GET /web-app/view-attendance`

```json theme={null}
{
  "success": true,
  "data": {
    "statistics": {
      "total_students": 500,
      "present_today": 485,
      "absent_today": 15
    },
    "monthly_percentage": "97%"
  }
}
```

***

## 6. Error Responses

| HTTP Code | Error Code      | Description                              |
| --------- | --------------- | ---------------------------------------- |
| 400       | INVALID\_PARAMS | Missing `roll_no` or invalid date format |
| 404       | NOT\_FOUND      | Student not found or no records for date |

***

## 7. Security Considerations

* **Scoping:** Data isolation is enforced via `skole_id`.
* **Role-Based Access:** Standard staff can view; only staff with `attendance.mark` perms can record.

***

## 8. Token Usage

```http theme={null}
GET /parent-app/attendance?roll_no=A001
Authorization: Bearer <JWT_TOKEN>
```

***

## 9. Token Refresh

Attendance endpoints do not trigger token refresh. Standard JWT rotation at the auth layer applies.

***

## 10. Logout / Session Invalidation

Not directly handled in this module.

***

## 11. Usage Example (cURL)

```bash theme={null}
curl -H "Authorization: Bearer <TOKEN>" \
"http://localhost:3000/parent-app/attendance?roll_no=A001"
```

***

## 12. Notes / Special Behaviors

* **Availability:** `availability_status` indicates if the student is currently on premises.
* **Bulk Imports:** The Web Admin app supports bulk attendance imports via CSV/Excel through a dedicated multipart endpoint.