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

# Write To (Parent Requests)

> Formal communication channel for leave applications, complaints, and general queries between parents and school staff.

## 1. API Purpose

The Write To module provides a structured ticketing system for parent-to-school communication. It replaces informal calls/notes with trackable threads for leave requests, complaints, and queries.

***

## 2. Endpoint Definition

| Method | Route                              | Auth   | Description                          |
| ------ | ---------------------------------- | ------ | ------------------------------------ |
| POST   | `/parent-app/write-to`             | 🔐 JWT | Submit a new request                 |
| GET    | `/parent-app/write-to`             | 🔐 JWT | View active/past requests            |
| GET    | `/parent-app/write-to/:id`         | 🔐 JWT | View full conversation thread        |
| POST   | `/parent-app/write-to/:id/reply`   | 🔐 JWT | Parent reply to a conversation       |
| GET    | `/teachers-app/write-to`           | 🔐 JWT | Staff: View all school requests      |
| POST   | `/teachers-app/write-to/:id/reply` | 🔐 JWT | Staff: reply to a request            |
| PUT    | `/teachers-app/write-to/:id`       | 🔐 JWT | Staff: Update status (e.g., Resolve) |

***

## 3. Authentication Flow

Standard JWT validation.

* Parents can only see requests they created (`parent_id` match).
* Staff can see all requests for their school (`skole_id` match).

***

## 4. Request Structure

#### POST /parent-app/write-to

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "parent_id": 1,
  "student_id": 45,
  "request_type": "leave_request",
  "subject": "Medical Leave for Aarav",
  "message": "Aarav has a mild fever...",
  "leave_from_date": "2024-03-17",
  "leave_to_date": "2024-03-17",
  "priority": "normal"
}
```

#### GET /parent-app/write-to

**Query Parameters:**

| Field  | Type   | Required | Description                       |
| ------ | ------ | -------- | --------------------------------- |
| status | string | No       | Filter by status (open/resolved). |

#### GET /parent-app/write-to/:id

**URL Parameters:**

| Field | Type   | Description               |
| ----- | ------ | ------------------------- |
| id    | number | ID of the request thread. |

#### POST /parent-app/write-to/:id/reply

**Request Body:**

```json theme={null}
{
  "replied_by_id": 1,
  "message": "Thank you for the update."
}
```

#### GET /teachers-app/write-to

**Query Parameters:**

| Field         | Type   | Required | Description                          |
| ------------- | ------ | -------- | ------------------------------------ |
| skole\_id     | string | Yes      | School identifier.                   |
| staff\_id     | string | No       | Filter by assigned staff.            |
| status        | string | No       | Filter by status (pending/resolved). |
| request\_type | string | No       | Filter by type.                      |

#### POST /teachers-app/write-to/:id/reply

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "replied_by_id": 10,
  "message": "Get well soon!",
  "attachment_url": "..."
}
```

#### PUT /teachers-app/write-to/:id

**Request Body:**

```json theme={null}
{
  "staff_id": 10,
  "status": "resolved"
}
```

***

## 5. Response Structure

#### Success: Request Submitted (201 Created)

**Route:** `POST /parent-app/write-to`

```json theme={null}
{
  "success": true,
  "message": "Request submitted",
  "data": { "id": 102 }
}
```

#### Success: Parent Request List (200 OK)

**Route:** `GET /parent-app/write-to`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 102,
      "subject": "Medical Leave",
      "status": "open",
      "created_at": "2024-03-16T09:00:00Z"
    }
  ]
}
```

#### Success: Full Thread View (200 OK)

**Route:** `GET /parent-app/write-to/:id`

```json theme={null}
{
  "success": true,
  "data": {
    "request": { "id": 102, "subject": "Medical Leave", "status": "open" },
    "replies": [
      { "id": 1, "message": "Get well soon!", "replied_by_id": 10 }
    ]
  }
}
```

#### Success: Staff Request Queue (200 OK)

**Route:** `GET /teachers-app/write-to`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 102,
      "parent_name": "Rajesh Kumar",
      "subject": "Medical Leave",
      "status": "pending"
    }
  ]
}
```

#### Success: Reply Posted (201 Created)

**Route:** `POST /{module}/write-to/:id/reply`

```json theme={null}
{
  "success": true,
  "message": "Reply sent successfully"
}
```

#### Success: Ticket Resolved (200 OK)

**Route:** `PUT /teachers-app/write-to/:id`

```json theme={null}
{
  "success": true,
  "message": "Request marked as resolved"
}
```

***

## 6. Error Responses

| HTTP Code | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| 403       | Forbidden: Attempting to access a request belonging to another parent |
| 400       | Missing `leave_from_date` for a leave type request                    |

***

## 7. Security Considerations

* **Thread Integrity:** Replies are linked via `write_to_id`.
* **Role Scoping:** Only staff with specific permissions can resolve tickets or assign them to others.

***

## 8. Token Usage

```http theme={null}
POST /parent-app/write-to
Authorization: Bearer <TOKEN>
```

***

## 9. Token Refresh

N/A.

***

## 10. Logout / Session Invalidation

N/A.

***

## 11. Usage Example (cURL)

```bash theme={null}
curl -X POST http://localhost:3000/parent-app/write-to \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"subject": "Query about Fee", "message": "...", "request_type": "query"}'
```

***

## 12. Notes / Special Behaviors

* **Leave Logic:** Submitting a `leave` type request automatically notifies the class teacher via push notification.
* **Auto-Close:** Inactive resolved threads are archived after a defined period (e.g., 30 days).