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

# Engagement (Comments & Reactions)

> Interactive system for parents and staff to engage with school content across multiple modules.

## 1. API Purpose

The Engagement API provides the interactive layer for the Skole platform. It allows parents and staff to acknowledge content (reactions) and ask clarifying questions (comments) on activities, diary entries, and notices.

***

## 2. Endpoint Definition

| Method | Route                                        | Auth   | Description                          |
| ------ | -------------------------------------------- | ------ | ------------------------------------ |
| POST   | `/parent-app/engagement/comment`             | 🔐 JWT | Post a new comment                   |
| GET    | `/parent-app/engagement/comments/:type/:id`  | 🔐 JWT | List comments for an entity          |
| POST   | `/parent-app/engagement/react`               | 🔐 JWT | Toggle a reaction (Like/Love)        |
| GET    | `/parent-app/engagement/reactions/:type/:id` | 🔐 JWT | Get counts and user's reaction state |

***

## 3. Authentication Flow

Standard JWT validation.

* All engagement is tied to the `parent_id` or `staff_id` extracted from the token.
* `skole_id` scoping ensures users only engage with content within their school.

***

## 4. Request Structure

#### POST /parent-app/engagement/comment

**Request Body:**

```json theme={null}
{
  "entity_type": "activity",
  "entity_id": 88,
  "content": "Looking forward to the sports day!"
}
```

#### POST /parent-app/engagement/react

**Request Body:**

```json theme={null}
{
  "entity_type": "diary",
  "entity_id": 501,
  "reaction_type": "love"
}
```

#### GET /parent-app/engagement/comments/:type/:id

**URL Parameters:**

| Field | Type   | Description                                    |
| ----- | ------ | ---------------------------------------------- |
| type  | string | Entity type (`activity`, `diary`, `write_to`). |
| id    | number | ID of the specific entity.                     |

#### GET /parent-app/engagement/reactions/:type/:id

**URL Parameters:**

| Field | Type   | Description  |
| ----- | ------ | ------------ |
| type  | string | Entity type. |
| id    | number | Entity ID.   |

***

## 5. Response Structure

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

**Route:** `POST /parent-app/engagement/comment`

```json theme={null}
{
  "success": true,
  "message": "Comment added",
  "data": { "id": 1001, "content": "Looking forward to it!" }
}
```

#### Success: Comment List (200 OK)

**Route:** `GET /parent-app/engagement/comments/:type/:id`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 1,
      "content": "Looking forward to it!",
      "author_name": "Ravi Kumar",
      "created_at": "2024-03-10T12:00:00Z"
    }
  ]
}
```

#### Success: Reaction Toggled (200 OK)

**Route:** `POST /parent-app/engagement/react`

```json theme={null}
{
  "success": true,
  "message": "Reaction updated",
  "data": { "reaction_type": "love", "active": true }
}
```

#### Success: Reaction Stats (200 OK)

**Route:** `GET /parent-app/engagement/reactions/:type/:id`

```json theme={null}
{
  "success": true,
  "data": {
    "love": 15,
    "thumbs_up": 22,
    "user_reaction": "love"
  }
}
```

***

## 6. Error Responses

| HTTP Code | Description                                                          |
| --------- | -------------------------------------------------------------------- |
| 400       | Invalid `entity_type` (must be activity/diary/write\_to/noticeboard) |
| 404       | Target entity not found                                              |

***

## 7. Security Considerations

* **Unique Constraint:** The database enforces a `@@unique([entity_type, entity_id, parent_id, staff_id])` constraint to prevent duplicate reactions from the same user.
* **Toggle Logic:** If the same `reaction_type` is sent twice, the reaction is removed (unlike standard social platforms).

***

## 8. Token Usage

```http theme={null}
POST /parent-app/engagement/react
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/engagement/comment \
-H "Authorization: Bearer <TOKEN>" \
-d '{"entity_type": "diary", "entity_id": 501, "content": "Done!"}'
```

***

## 12. Notes / Special Behaviors

* **Cross-Module Linkage:** The `entity_type` field allows one API to handle engagement for multiple modules without logic duplication.
* **Moderation:** Deleted comments (`deleted_status = 1`) are filtered out at the service layer during listing.