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

> SKOLE-CALS — Academic Calendar Module

# SKOLE-CALS — Academic Calendar Module

**Module ID:** `SKOLE-CALS` | **Version:** 1.0 | **Status:** Active\
**Products:** Parent App (read) · Teacher App (manage) · Web App (manage)

***

## 1. Overview

| Field              | Value                                                                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Module Name**    | Academic Calendar                                                                                                                                                                   |
| **Module Code**    | CALS                                                                                                                                                                                |
| **Business Value** | Gives the whole school community a single source of truth for the academic year's events — exam dates, holidays, sports days, PTMs. Reduces missed events and scheduling conflicts. |

### Scope In

* Create, update, soft-delete academic events with date range, event type, time
* Parent and Teacher views of upcoming events
* Filter by event\_type

### Scope Out

* iCal export / Google Calendar sync
* Parent RSVP

***

## 2. Requirements

### Functional Requirements (FR)

*What the module must DO — actions, behaviors, and outcomes.*

* **SKOLE-CALS-FR001:** The module shall allow admins and teachers to create academic events with titles, descriptions, types, date ranges (from/to), and times.
* **SKOLE-CALS-FR002:** The module shall support categorized event types: holiday, exam, sports, ptm, cultural, and other.
* **SKOLE-CALS-FR003:** The module shall enable authorized users to update and soft-delete calendar events.
* **SKOLE-CALS-FR004:** The module shall allow all users to view upcoming school events, filterable by their type.
* **SKOLE-CALS-FR005:** The module shall perform chronological display of events, sorted by the start date in ascending order.

### Non-Functional Requirements (NFR)

*How well the module must do it — performance, security, and reliability.*

* **SKOLE-CALS-NFR001:** The module shall behave reliably by excluding soft-deleted events (`deleted_status = 1`) from visibility across all apps.
* **SKOLE-CALS-NFR002:** The module shall perform multi-tenant isolation by scoping all events strictly to the school's `skole_id`.

### Constraints

*Rules and boundaries — tech choices and platform restrictions.*

* **C001:** We must implement event duration support where the end date can differ from the start date to accommodate multi-day events like exams or sports days.
* **C002:** We must use a dedicated `academic_events` table to separate formal calendar dates from activity-based social content.

***

## 3. Sub-modules / Backlog

| ID                 | Sub-module                       | Priority | Status | Estimate | Linked FR   |
| ------------------ | -------------------------------- | -------- | ------ | -------- | ----------- |
| `SKOLE-CALS-SM001` | Event management (teacher/admin) | P0       | Done   | 2d       | FR001–FR003 |
| `SKOLE-CALS-SM002` | Calendar viewer (all apps)       | P0       | Done   | 1d       | FR004–FR005 |

***

## 4. Logical Implementation

```
GET /teachers-app/academic-calendar?skole_id=&event_type=
  WHERE deleted_status = 0 AND skole_id = ?
  ORDER BY event_from_date ASC

POST /teachers-app/academic-calendar
  { skole_id, title, description, event_type,
    event_from_date, event_to_date, event_time }
```

***

## 5. UI Requirements

### Teacher App — CalendarScreen

| ID                 | Screen         | Route       | Description                                           |
| ------------------ | -------------- | ----------- | ----------------------------------------------------- |
| `SKOLE-CALS-UI001` | CalendarScreen | `/calendar` | Monthly calendar with event markers, event list below |

**Components:**

| ID                 | Component         | Props                             |
| ------------------ | ----------------- | --------------------------------- |
| `SKOLE-CALS-UC001` | `EventCard`       | `event`, `onEdit`, `onDelete`     |
| `SKOLE-CALS-UC002` | `EventTypeFilter` | `types[]`, `selected`, `onChange` |
| `SKOLE-CALS-UC003` | `EventForm`       | `initialValues`, `onSubmit`       |
| `SKOLE-CALS-UC004` | `CalendarMarker`  | `date`, `hasEvent`, `eventType`   |

### Parent App — AcademicCalendarScreen

| ID                 | Screen           | Route                | Description                              |
| ------------------ | ---------------- | -------------------- | ---------------------------------------- |
| `SKOLE-CALS-UI002` | AcademicCalendar | `/academic-calendar` | Read-only view of school calendar events |

### Web App

| ID                 | Screen        | Route                | Description                   |
| ------------------ | ------------- | -------------------- | ----------------------------- |
| `SKOLE-CALS-UI003` | Calendar Page | `/:skoleId/calendar` | Full CRUD calendar management |

***

## 6. Conditional Expressions

| ID                 | Expression                          | Trigger          | True Action          | False Action     |
| ------------------ | ----------------------------------- | ---------------- | -------------------- | ---------------- |
| `SKOLE-CALS-CE001` | `deleted_status === 1`              | DB query         | Exclude              | Include          |
| `SKOLE-CALS-CE002` | `event_type === 'holiday'`          | EventCard render | Green highlight      | Normal           |
| `SKOLE-CALS-CE003` | `event_type === 'exam'`             | EventCard render | Red highlight        | Normal           |
| `SKOLE-CALS-CE004` | `event_to_date !== event_from_date` | EventCard render | Show date range      | Show single date |
| `SKOLE-CALS-CE005` | `user.type === 'staff'`             | Calendar screen  | Show add/edit/delete | Read-only        |

***

## 7. Database Tables

| ID                 | Table             | Role                         |
| ------------------ | ----------------- | ---------------------------- |
| `SKOLE-CALS-TB001` | `academic_events` | All academic calendar events |

***

## 8. API Endpoints

| ID                 | Method | Route                                 | Auth         | Description        |
| ------------------ | ------ | ------------------------------------- | ------------ | ------------------ |
| `SKOLE-CALS-EP001` | GET    | `/parent-app/academic-events`         | JWT (parent) | View events        |
| `SKOLE-CALS-EP002` | GET    | `/teachers-app/academic-calendar`     | JWT (staff)  | View events        |
| `SKOLE-CALS-EP003` | POST   | `/teachers-app/academic-calendar`     | JWT (staff)  | Create event       |
| `SKOLE-CALS-EP004` | PUT    | `/teachers-app/academic-calendar/:id` | JWT (staff)  | Update event       |
| `SKOLE-CALS-EP005` | DELETE | `/teachers-app/academic-calendar/:id` | JWT (staff)  | Soft-delete event  |
| `SKOLE-CALS-EP006` | GET    | `/web-app/academic-calendar`          | JWT (user)   | Admin view events  |
| `SKOLE-CALS-EP007` | POST   | `/web-app/academic-calendar`          | JWT (user)   | Admin create event |
| `SKOLE-CALS-EP008` | PUT    | `/web-app/academic-calendar/:id`      | JWT (user)   | Admin update event |
| `SKOLE-CALS-EP009` | DELETE | `/web-app/academic-calendar/:id`      | JWT (user)   | Admin delete event |