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

# Noticeboard

> Formal school broadcasts, including circulars, exam schedules, fee reminders, and holiday announcements.

## 1. API Purpose

The Noticeboard API serves as the school's official broadcast channel. It provides a permanent and searchable record of formal announcements, replacing physical notice boards.

***

## 2. Endpoint Definition

| Method | Route                       | Auth   | Description                       |
| ------ | --------------------------- | ------ | --------------------------------- |
| GET    | `/parent-app/noticeboard`   | 🔐 JWT | View official school notices      |
| GET    | `/teachers-app/noticeboard` | 🔐 JWT | View official school notices      |
| GET    | `/web-app/noticeboard`      | 🔐 JWT | Admin: View school-wide notices   |
| POST   | `/web-app/noticeboard`      | 🔐 JWT | Admin: Create a new formal notice |
| PUT    | `/web-app/noticeboard/:id`  | 🔐 JWT | Admin: Update notice content      |
| DELETE | `/web-app/noticeboard/:id`  | 🔐 JWT | Admin: Soft-delete a notice       |

***

## 3. Authentication Flow

Standard JWT validation. All parents and staff within the same school (`skole_id`) see the same global noticeboard feed.

***

## 4. Request Structure

#### GET /parent-app/noticeboard

**Headers:**

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

#### GET /teachers-app/noticeboard

**Query Parameters:**

| Field        | Type   | Required | Description        |
| ------------ | ------ | -------- | ------------------ |
| skole\_id    | string | Yes      | School identifier. |
| notice\_type | string | No       | Filter by type.    |

#### GET /web-app/noticeboard

**Query Parameters:**

| Field     | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| skole\_id | string | Yes      | School identifier.              |
| page      | number | No       | Page number (Default: 1).       |
| limit     | number | No       | Records per page (Default: 10). |

#### POST /web-app/noticeboard

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "notice_title": "Summer Vacation Schedule",
  "notice_desc": "The school will remain closed from April 1st to April 15th.",
  "notice_type": "holiday"
}
```

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

**Request Body:**

```json theme={null}
{
  "notice_title": "Updated holiday Schedule",
  "notice_desc": "..."
}
```

#### DELETE /web-app/noticeboard/:id

**URL Parameters:**

| Field | Type   | Description                 |
| ----- | ------ | --------------------------- |
| id    | number | ID of the notice to delete. |

***

## 5. Response Structure

#### Success: Parent Notice Feed (200 OK)

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

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 12,
      "notice_title": "Sports Day Schedule",
      "notice_type": "event",
      "created_at": "2024-03-01T10:00:00Z"
    }
  ]
}
```

#### Success: Teacher Notice Feed (200 OK)

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

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 12,
      "notice_title": "Staff Meeting",
      "notice_type": "meeting",
      "skole_id": "SKL001"
    }
  ]
}
```

#### Success: Admin Notice List (200 OK)

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

```json theme={null}
{
  "success": true,
  "data": {
    "notices": [...],
    "count": 50
  }
}
```

#### Success: Notice Created (201 Created)

**Route:** `POST /web-app/noticeboard`

```json theme={null}
{
  "success": true,
  "message": "Notice published",
  "data": { "id": 13 }
}
```

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

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

```json theme={null}
{
  "success": true,
  "message": "Notice content updated"
}
```

#### Success: Notice Deleted (200 OK)

**Route:** `DELETE /web-app/noticeboard/:id`

```json theme={null}
{
  "success": true,
  "message": "Notice archived"
}
```

***

## 6. Error Responses

| HTTP Code | Description                        |
| --------- | ---------------------------------- |
| 404       | Notice not found                   |
| 400       | Missing `notice_title` in creation |

***

## 7. Security Considerations

* **Integrity:** Only users with `noticeboard.create` staff permissions can broadcast notices.
* **Soft Delete:** `notice_deleted = 1` removes the notice from public view while preserving audit logs.

***

## 8. Token Usage

```http theme={null}
GET /parent-app/noticeboard
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/parent-app/noticeboard?notice_type=exam"
```

***

## 12. Notes / Special Behaviors

* **Typing:** Notice types determine the color-coding in the mobile app (e.g., Blue for `exam`, Orange for `fee`).
* **Persistence:** Unlike Activities, notices are generally long-lived and pinned to the top of the feed if marked as high importance.