> ## 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.

# Student Management

> Core student registry, covering profiles, guardian details, address management, and enrollment lifecycle.

## 1. API Purpose

The Student Management API is the central registry of the Skole platform. It powers all other modules by establishing student identities and linking them to parents, staff, and school-specific data.

***

## 2. Endpoint Definition

| Method | Route                                  | Auth   | Description                      |
| ------ | -------------------------------------- | ------ | -------------------------------- |
| GET    | `/parent-app/student-detail`           | 🔐 JWT | View child's full profile        |
| GET    | `/teachers-app/students`               | 🔐 JWT | List assigned students (Teacher) |
| GET    | `/web-app/students`                    | 🔐 JWT | Full student registry (Admin)    |
| PUT    | `/web-app/students/:id`                | 🔐 JWT | Update student record            |
| POST   | `/web-app/students/:id/archive`        | 🔐 JWT | Archive student record           |
| POST   | `/web-app/students/:id/reset-password` | 🔐 JWT | Reset parent PIN                 |

***

## 3. Authentication Flow

* **Guardians:** Access is restricted to children linked to the parent's `phone_no` in the database.
* **Teachers:** Access is restricted to students assigned to them via the `staff_student` junction table.
* **Admins:** Full access scoped by `skole_id`.

***

## 4. Request Structure

#### GET /teachers-app/students

**Query Parameters:**

| Field     | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| skole\_id | string | Yes      | School identifier.     |
| grade     | string | No       | Filter by grade/class. |

#### GET /web-app/students

**Query Parameters:**

| Field     | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| skole\_id | string | Yes      | School identifier.                 |
| search    | string | No       | Search by name or roll number.     |
| grade     | string | No       | Filter by grade/class.             |
| status    | string | No       | Enum: `active`, `archived`, `all`. |
| page      | number | No       | Default: 1.                        |
| limit     | number | No       | Default: 10.                       |

#### PUT /web-app/students/:id

**Request Body:**

```json theme={null}
{
  "student_full_name": "Aarav Sharma",
  "gender": "Male",
  "grade": "Grade 5-A",
  "date_of_birth": "2013-05-15",
  "blood_group": "B+",
  "phone_no": "9876543210"
}
```

#### POST /web-app/students/:id/archive

**URL Parameters:**

| Field | Type   | Description            |
| ----- | ------ | ---------------------- |
| id    | number | Student ID to archive. |

#### POST /web-app/students/:id/reset-password

**Request Body:**

```json theme={null}
{
  "password": "NewSecurePassword123"
}
```

***

## 5. Response Structure

#### Success: Child Profile Detail (200 OK)

**Route:** `GET /parent-app/student-detail`

```json theme={null}
{
  "success": true,
  "data": {
    "student": {
      "id": 45,
      "student_full_name": "Aarav Sharma",
      "roll_no": "20240045",
      "grade": "Grade 5-A"
    },
    "guardian": { "father_name": "Rajesh Kumar" }
  }
}
```

#### Success: Teacher Student List (200 OK)

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

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 45,
      "student_full_name": "Aarav Sharma",
      "roll_no": "20240045"
    }
  ]
}
```

#### Success: Admin Student Registry (200 OK)

**Route:** `GET /web-app/students`

```json theme={null}
{
  "success": true,
  "data": {
    "students": [...],
    "pagination": { "total": 1200, "page": 1 }
  }
}
```

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

**Route:** `PUT /web-app/students/:id`

```json theme={null}
{
  "success": true,
  "message": "Student record updated successfully"
}
```

#### Success: Record Archived (200 OK)

**Route:** `POST /web-app/students/:id/archive`

```json theme={null}
{
  "success": true,
  "message": "Student moved to archives"
}
```

#### Success: PIN Reset (200 OK)

**Route:** `POST /web-app/students/:id/reset-password`

```json theme={null}
{
  "success": true,
  "message": "Parent PIN has been reset"
}
```

***

## 6. Error Responses

| HTTP Code | Description                                             |
| --------- | ------------------------------------------------------- |
| 404       | Student not found                                       |
| 403       | Attempting to access a student not assigned to the user |

***

## 7. Security Considerations

* **PIN Security:** Resetting a PIN requires Admin-level JWT.
* **Isolation:** Cross-tenant access is blocked via the global `SkoleGuard`.

***

## 8. Token Usage

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

***

## 9. Token Refresh

N/A.

***

## 10. Logout / Session Invalidation

N/A.

***

## 11. Usage Example (cURL)

```bash theme={null}
curl -H "Authorization: Bearer <TOKEN>" \
"http://localhost:3000/web-app/students?grade=Grade%205"
```

***

## 12. Notes / Special Behaviors

* **Lifecycle:** Students can move from `registered` to `active`, `inactive`, and eventually `archived`.
* **Roll Numbers:** Roll numbers must be unique within a school (`skole_id`).