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

# Academic Calendar

> Centralized scheduling for the academic year, including holidays, exams, sports days, and PTMs.

## 1. API Purpose

The Academic Calendar API provides a single source of truth for the school's annual events. It helps parents and staff stay aligned on important dates, reducing scheduling conflicts and missed milestones.

***

## 2. Endpoint Definition

| Method | Route                                         | Auth   | Description                        |
| ------ | --------------------------------------------- | ------ | ---------------------------------- |
| GET    | `/parent-app/academic-events`                 | 🔐 JWT | View upcoming academic events      |
| GET    | `/teachers-app/academic-calendar`             | 🔐 JWT | Staff: View all scheduled events   |
| POST   | `/teachers-app/academic-calendar`             | 🔐 JWT | Staff: Create a new academic event |
| PUT    | `/teachers-app/academic-calendar/:id`         | 🔐 JWT | Staff: Update event details        |
| DELETE | `/teachers-app/academic-calendar/:id`         | 🔐 JWT | Staff: Soft-delete an event        |
| GET    | `/web-app/academic-calendar`                  | 🔐 JWT | Admin: Comprehensive event list    |
| POST   | `/web-app/academic-calendar`                  | 🔐 JWT | Admin: Create academic event       |
| POST   | `/web-app/bulk-import-academic-calendar-json` | 🔐 JWT | Admin: Bulk import from JSON       |

***

## 3. Authentication Flow

Standard Bearer JWT validation. Access is school-specific (`skole_id`). Staff require specific RBAC permission to manage the calendar.

***

## 4. Request Structure

#### GET /parent-app/academic-events

**Headers:**

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

#### GET /web-app/academic-calendar

**Query Parameters:**

| Field       | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| skole\_id   | string | Yes      | School identifier.              |
| event\_type | string | No       | Filter by type (holiday/event). |
| from\_date  | string | No       | Start date filter (YYYY-MM-DD). |
| to\_date    | string | No       | End date filter (YYYY-MM-DD).   |

#### POST /web-app/academic-calendar

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "title": "Annual Day Celebration",
  "description": "Grand celebration in the school auditorium.",
  "event_type": "event",
  "event_from_date": "2024-12-20T00:00:00Z",
  "event_to_date": "2024-12-20T00:00:00Z",
  "event_time": "10:00 AM"
}
```

#### PUT /teachers-app/academic-calendar/:id

**Request Body:**

```json theme={null}
{
  "title": "Updated Event Title",
  "event_time": "11:00 AM"
}
```

#### DELETE /teachers-app/academic-calendar/:id

**URL Parameters:**

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

#### POST /web-app/bulk-import-academic-calendar-json

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "records": [
    {
      "title": "Winter Break",
      "event_type": "holiday",
      "event_from_date": "2024-12-24",
      "event_to_date": "2025-01-02"
    }
  ]
}
```

***

## 5. Response Structure

#### Success: Parent Event View (200 OK)

**Route:** `GET /parent-app/academic-events`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 45,
      "title": "Sports Day",
      "event_type": "event",
      "event_from_date": "2024-12-20"
    }
  ]
}
```

#### Success: Staff Calendar List (200 OK)

**Route:** `GET /teachers-app/academic-calendar`

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 45,
      "title": "Sports Day",
      "event_type": "event",
      "skole_id": "SKL001"
    }
  ]
}
```

#### Success: Event Created (201 Created)

**Route:** `POST /{module}/academic-calendar`

```json theme={null}
{
  "success": true,
  "message": "Academic event added",
  "data": { "id": 46 }
}
```

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

**Route:** `PUT /teachers-app/academic-calendar/:id`

```json theme={null}
{
  "success": true,
  "message": "Event details updated"
}
```

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

**Route:** `DELETE /teachers-app/academic-calendar/:id`

```json theme={null}
{
  "success": true,
  "message": "Event removed"
}
```

#### Success: Admin Event Dashboard (200 OK)

**Route:** `GET /web-app/academic-calendar`

```json theme={null}
{
  "success": true,
  "data": {
    "events": [...],
    "total_count": 25
  }
}
```

#### Success: Bulk Import JSON (200 OK)

**Route:** `POST /web-app/bulk-import-academic-calendar-json`

```json theme={null}
{
  "success": true,
  "message": "Bulk import successful",
  "data": { "count": 10 }
}
```

***

## 6. Error Responses

| HTTP Code | Description                                  |
| --------- | -------------------------------------------- |
| 404       | Event not found                              |
| 400       | Date format error or missing required fields |

***

## 7. Security Considerations

* **Scoping:** Enforced via `skole_id`.
* **RBAC:** Only staff with `calendar.manage` permission can create or edit events.

***

## 8. Token Usage

```http theme={null}
GET /parent-app/academic-events
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/academic-events?event_type=holiday"
```

***

## 12. Notes / Special Behaviors

* **Multi-day Events:** If `event_to_date` is different from `event_from_date`, the mobile app displays the event as a span across the calendar.
* **Color Coding:** Similar to the Noticeboard, event types trigger specific UI highlights (e.g., Red for `exam`, Green for `holiday`).