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

# Digital Diary Module

> SKOLE-DIRY — Digital Diary Module

# SKOLE-DIRY — Digital Diary Module

**Module ID:** `SKOLE-DIRY` | **Version:** 1.0 | **Status:** Active\
**Products:** Parent App (read/status update) · Teacher App (create/manage) · Web App (view)

***

## 1. Overview

| Field              | Value                                                                                                                                                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Module Name**    | Digital Diary                                                                                                                                                                                              |
| **Module Code**    | DIRY                                                                                                                                                                                                       |
| **Business Value** | Replaces physical homework diaries. Teachers post assignments with due dates, priority levels, and attachments. Parents view and mark homework as completed, keeping both sides aligned on academic tasks. |

### Scope In

* Teachers: Create, edit, delete diary entries (homework, classwork, notes, reminders)
* Parents: View diary entries for their child, mark as completed
* Filtering by grade, student, diary type, status

### Scope Out

* File upload (attachment\_url stored but upload handled externally)
* Student self-service diary access

***

## 2. Requirements

### Functional Requirements (FR)

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

* **SKOLE-DIRY-FR001:** The module shall allow teachers to create diary entries with title, description, grade, type (homework, classwork, note, reminder), due date, priority, and optional attachment URLs.
* **SKOLE-DIRY-FR002:** The module shall allow targeting diary entries to either an entire grade or a specific student.
* **SKOLE-DIRY-FR003:** The module shall enable teachers to update and soft-delete diary entries.
* **SKOLE-DIRY-FR004:** The module shall allows parents to view all relevant diary entries for their child's grade or student ID.
* **SKOLE-DIRY-FR005:** The module shall allow parents to mark a diary entry as 'completed' for their child.
* **SKOLE-DIRY-FR006:** The module shall support priority levels: low, medium, and high.
* **SKOLE-DIRY-FR007:** The module shall allows web admins to view all diary activities across the school.

### Non-Functional Requirements (NFR)

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

* **SKOLE-DIRY-NFR001:** The module shall behave reliably by ensuring soft-deleted entries (`deleted_status = 1`) never appear in consumer API responses.
* **SKOLE-DIRY-NFR002:** The module shall perform visual highlighting for overdue pending tasks in the parent application.
* **SKOLE-DIRY-NFR003:** The module shall ensure that diary entries are delivered to parents with minimal latency after being published by a teacher.

### Constraints

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

* **C001:** We must implement soft-deletion using a `deleted_status` flag because the platform architecture avoids permanent data removal for audit purposes.
* **C002:** We must use external file storage for attachments as the platform does not currently host raw binary assets for diary entries.

***

## 3. Sub-modules / Backlog

| ID                 | Sub-module                      | Priority | Status  | Estimate | Linked FR   |
| ------------------ | ------------------------------- | -------- | ------- | -------- | ----------- |
| `SKOLE-DIRY-SM001` | Teacher diary management (CRUD) | P0       | Done    | 3d       | FR001–FR003 |
| `SKOLE-DIRY-SM002` | Parent diary viewer             | P0       | Done    | 2d       | FR004–FR005 |
| `SKOLE-DIRY-SM003` | Web admin diary view            | P1       | Done    | 1d       | FR008       |
| `SKOLE-DIRY-SM004` | File attachment support         | P2       | Partial | —        | FR001       |

***

## 4. Logical Implementation

### Entry Lifecycle State Machine

```text theme={null}
[draft] ──publish──→ [published] ──parent marks done──→ [completed]
[published] ──teacher edits──→ [published]
[published] ──teacher deletes──→ [deleted] (deleted_status = 1, hidden)
```

### Teacher Create Flow

```text theme={null}
POST /teachers-app/digital-diary
  ├─ Input: { skole_id, staff_id, grade, diary_type, title, description,
  │           due_date, priority, status, attachment_url, student_id? }
  └─ Insert into digital_diary → return created entry
```

### Parent View Flow

```text theme={null}
GET /parent-app/digital-diary?grade=&student_id=&diary_type=&status=
  ├─ JWT → extract skole_id
  ├─ Filter: WHERE skole_id = jwt.skole_id AND deleted_status = 0
  │          AND (grade = ? OR student_id = ?) 
  └─ Return entries sorted by due_date ASC
```

### Parent Status Update Flow

```text theme={null}
PUT /parent-app/digital-diary/:id
  ├─ Input: { status: 'completed' }
  └─ Update digital_diary SET status = 'completed' WHERE id = :id
```

### Error Handling

| Scenario            | HTTP | Message                               |
| ------------------- | ---- | ------------------------------------- |
| Entry not found     | 404  | "Diary entry not found"               |
| Invalid diary\_type | 400  | Validation error                      |
| Soft-deleted entry  | 404  | "Not found" (filtered at query level) |

***

## 5. UI Requirements

### Parent App — DiaryScreen

| ID                 | Screen      | Route    | Description                                                               |
| ------------------ | ----------- | -------- | ------------------------------------------------------------------------- |
| `SKOLE-DIRY-UI001` | DiaryScreen | `/diary` | Filtered list of diary entries grouped by due date with status indicators |

**Components:**

| ID                 | Component         | Props                                  |        |        |
| ------------------ | ----------------- | -------------------------------------- | ------ | ------ |
| `SKOLE-DIRY-UC001` | `DiaryCard`       | `entry`, `onMarkComplete`, `isOverdue` |        |        |
| `SKOLE-DIRY-UC002` | `DiaryTypeFilter` | `types[]`, `selected`, `onChange`      |        |        |
| `SKOLE-DIRY-UC003` | `PriorityBadge`   | \`priority: low                        | medium | high\` |
| `SKOLE-DIRY-UC004` | `DueDateChip`     | `due_date`, `isOverdue`                |        |        |
| `SKOLE-DIRY-UC005` | `AttachmentLink`  | `url`                                  |        |        |

**UI States:**

* **Loading:** 3 skeleton cards
* **Empty:** "No diary entries for this period"
* **Error:** Toast + retry button

### Teacher App — DiaryScreen

| ID                 | Screen      | Route    | Description                                                                  |
| ------------------ | ----------- | -------- | ---------------------------------------------------------------------------- |
| `SKOLE-DIRY-UI002` | DiaryScreen | `/diary` | Full CRUD interface for managing diary entries, with grade/student selectors |

**Additional Components:**

| ID                 | Component            | Props                                  |
| ------------------ | -------------------- | -------------------------------------- |
| `SKOLE-DIRY-UC006` | `DiaryForm`          | `initialValues`, `onSubmit`, `loading` |
| `SKOLE-DIRY-UC007` | `GradeStudentPicker` | `grades[]`, `students[]`, `onSelect`   |
| `SKOLE-DIRY-UC008` | `DeleteConfirmModal` | `onConfirm`, `onCancel`                |

### Web App — Diary Page

| ID                 | Screen     | Route             | Description                                                     |
| ------------------ | ---------- | ----------------- | --------------------------------------------------------------- |
| `SKOLE-DIRY-UI003` | Diary Page | `/:skoleId/diary` | Read-only tabular view with filters for grade, type, date range |

***

## 6. Conditional Expressions

| ID                 | Expression                                               | Trigger              | True Action               | False Action              |
| ------------------ | -------------------------------------------------------- | -------------------- | ------------------------- | ------------------------- |
| `SKOLE-DIRY-CE001` | `entry.deleted_status === 1`                             | DB query             | Exclude from results      | Include                   |
| `SKOLE-DIRY-CE002` | `entry.due_date < today && entry.status !== 'completed'` | DiaryCard render     | Show overdue badge (red)  | Normal style              |
| `SKOLE-DIRY-CE003` | `entry.status === 'completed'`                           | DiaryCard render     | Show checkmark, grey out  | Show pending style        |
| `SKOLE-DIRY-CE004` | `entry.priority === 'high'`                              | DiaryCard render     | Red PriorityBadge         | Normal badge color        |
| `SKOLE-DIRY-CE005` | `entry.student_id !== null`                              | Teacher query filter | Target specific student   | Target whole grade        |
| `SKOLE-DIRY-CE006` | `entry.attachment_url !== null`                          | DiaryCard render     | Show attachment link      | Hide attachment section   |
| `SKOLE-DIRY-CE007` | `user.type === 'staff'`                                  | Diary screen render  | Show edit/delete controls | Hide teacher-only actions |

***

## 7. Internal Module Connections

| Direction   | Module     | Data / Event                                                             | Condition                   |
| ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------- |
| DIRY → AUTH | Auth       | JWT `skole_id` scopes all queries                                        | Every request               |
| DIRY → STUD | Students   | `student_id` links entry to a specific student                           | When student-specific entry |
| ENGG → DIRY | Engagement | Comments and reactions attach to diary entries via `entity_type='diary'` | On comment/react action     |
| DASH → DIRY | Dashboard  | Pending diary count shown on parent dashboard                            | Dashboard load              |

***

## 8. External Connections

| ID                 | Service                  | Purpose                                      | Failure Behavior          |
| ------------------ | ------------------------ | -------------------------------------------- | ------------------------- |
| `SKOLE-DIRY-EX001` | PostgreSQL (Prisma)      | Read/write `digital_diary`                   | 500 error                 |
| `SKOLE-DIRY-EX002` | File Storage (URL-based) | `attachment_url` links to external file host | Broken link shown to user |

***

## 9. Database Tables

| ID                 | Table           | Role              |
| ------------------ | --------------- | ----------------- |
| `SKOLE-DIRY-TB001` | `digital_diary` | All diary entries |

### `digital_diary` Schema

| Column           | Type         | Notes                            |
| ---------------- | ------------ | -------------------------------- |
| `id`             | Int PK       | Auto-increment                   |
| `skole_id`       | VarChar(15)  | School tenant key                |
| `staff_id`       | Int          | Teacher who created it           |
| `grade`          | VarChar(50)  | Target grade                     |
| `student_id`     | Int?         | Specific student (optional)      |
| `diary_type`     | VarChar(50)  | homework/classwork/note/reminder |
| `title`          | VarChar(255) | Entry title                      |
| `description`    | Text         | Full entry content               |
| `due_date`       | Date         | Completion deadline              |
| `attachment_url` | VarChar(500) | External file link               |
| `priority`       | VarChar(25)  | low/medium/high                  |
| `status`         | VarChar(25)  | pending/completed                |
| `deleted_status` | Int          | 0=active, 1=deleted              |
| `created_at`     | Timestamp    | —                                |
| `updated_at`     | Timestamp    | —                                |

***

## 10. API Endpoints Summary

| ID        | Method | Route                                       | Auth | Description                |
| --------- | ------ | ------------------------------------------- | ---- | -------------------------- |
| PARENT-01 | GET    | `/parent-app/digital-diary`                 | JWT  | List child's diary entries |
| PARENT-02 | GET    | `/parent-app/digital-diary/:id`             | JWT  | Read single entry          |
| PARENT-03 | PUT    | `/parent-app/digital-diary/:id`             | JWT  | Mark entry completed       |
| PARENT-04 | POST   | `/parent-app/digital-diary/:id/attachments` | JWT  | Upload attachment          |
| TEACH-01  | GET    | `/teachers-app/digital-diary`               | JWT  | List all entries           |
| TEACH-02  | GET    | `/teachers-app/digital-diary/:id`           | JWT  | Read entry detail          |
| TEACH-03  | POST   | `/teachers-app/digital-diary`               | JWT  | Create entry               |
| TEACH-04  | PUT    | `/teachers-app/digital-diary/:id`           | JWT  | Update entry               |
| TEACH-05  | DELETE | `/teachers-app/digital-diary/:id`           | JWT  | Delete entry               |
| ADMIN-01  | GET    | `/web-app/digital-diary`                    | JWT  | List all entries           |
| ADMIN-02  | GET    | `/web-app/digital-diary/:id`                | JWT  | View entry detail          |
| ADMIN-03  | POST   | `/web-app/digital-diary`                    | JWT  | Create entry               |

***

* Default sort: by due\_date ascending

### PARENT-01: List Child's Diary Entries

#### Section 1: Endpoint Summary

Returns all diary entries visible to parent for their child, including homework, classwork notes, and reminders. Filters by priority, type, and status.

#### Section 2: HTTP Details

* **HTTP Method:** GET
* **Endpoint URL:** `/parent-app/digital-diary`
* **Authentication:** JWT Bearer Token (Parent)
* **Rate Limit:** 100 requests per minute

#### Section 4: Query Parameters

| Parameter   | Type    | Required | Default     | Description                                 |
| ----------- | ------- | -------- | ----------- | ------------------------------------------- |
| diary\_type | String  | No       | -           | Filter: homework, classwork, note, reminder |
| status      | String  | No       | pending     | Filter: pending, completed                  |
| priority    | String  | No       | -           | Filter: low, medium, high                   |
| from\_date  | Date    | No       | 30 days ago | Start date                                  |
| to\_date    | Date    | No       | Today       | End date                                    |
| take        | Integer | No       | 20          | Page size                                   |
| skip        | Integer | No       | 0           | Offset                                      |

#### Section 6: Response Schema (Success - 200)

```json theme={null}
{
  "status": "success",
  "data": {
    "entries": [
      {
        "id": "UUID",
        "title": "Math Chapter 5 Homework",
        "description": "Complete exercises 1-20 from page 45",
        "diary_type": "homework",
        "priority": "high",
        "status": "pending",
        "due_date": "2026-03-18",
        "created_by": "Mr. Vikram Kumar",
        "created_at": "2026-03-16T10:00:00.000Z",
        "attachment_url": "https://cdn.skole.com/diary/pdf123.pdf"
      }
    ],
    "pagination": {
      "total": 12,
      "take": 20,
      "skip": 0
    }
  }
}
```

#### Section 7: Error Responses

**401 - Unauthorized**

```json theme={null}
{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid JWT token"
}
```

**404 - No Entries**

```json theme={null}
{
  "status": "success",
  "data": {
    "entries": [],
    "pagination": {"total": 0}
  }
}
```

#### Section 8: Implementation Examples

**JavaScript:**

```javascript theme={null}
const getChildDiary = async (token, filters = {}) => {
  const params = new URLSearchParams({
    status: 'pending',
    take: 20,
    ...filters
  });

  const response = await fetch(
    `https://api.skole.com/v1/parent-app/digital-diary?${params}`,
    {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  const data = await response.json();
  return data.data.entries;
};

// Usage
const homeworks = await getChildDiary(token, { diary_type: 'homework' });
```

**Python:**

```python theme={null}
def get_child_diary(token: str, diary_type: str = None) -> list:
    url = 'https://api.skole.com/v1/parent-app/digital-diary'
    headers = {'Authorization': f'Bearer {token}'}
    
    params = {
        'status': 'pending',
        'take': 20
    }
    if diary_type:
        params['diary_type'] = diary_type
    
    response = requests.get(url, headers=headers, params=params)
    data = response.json()
    return data['data']['entries']
```

#### Section 9: Database Context

**Tables:**

* digital\_diary (primary)
* students (join for access control)

**Query:**

```sql theme={null}
SELECT dd.* FROM digital_diary dd
JOIN students s ON s.grade = dd.grade
WHERE s.parent_id = ? AND s.skole_id = ? 
  AND dd.deleted_status = 0
  AND dd.due_date >= ? AND dd.due_date <= ?
ORDER BY dd.due_date ASC
```

**Indices:** (skole\_id, grade), (skole\_id, deleted\_status), due\_date

#### Section 10: Business Logic & Validations

**Filtering:**

* Automatically hides deleted entries (deleted\_status = 1)
* Scopes to parent's school and child's grade
* Respects privacy: parents see only entries for their child's grade/student
* Default sort: by due\_date ascending

#### Section 11: Related Endpoints

* **GET** `/parent-app/digital-diary/:id` - Single entry detail
* **PUT** `/parent-app/digital-diary/:id` - Mark completed
* **POST** `/parent-app/digital-diary/:id/attachments` - Upload file

#### Section 12: Response Summary Table

| Status | Scenario     | Error Code   | Message           |
| ------ | ------------ | ------------ | ----------------- |
| 200 ✅  | Success      | -            | Entries retrieved |
| 401 ❌  | Unauthorized | UNAUTHORIZED | Invalid token     |

***

### PARENT-02: Get Diary Entry Detail

#### Section 1: Endpoint Summary

Fetch complete details of a single diary entry including full description, attachments, and completion status.

#### Section 2: HTTP Details

* **HTTP Method:** GET
* **Endpoint URL:** `/parent-app/digital-diary/:id`
* **Authentication:** JWT (Parent)

#### Section 3: Path Parameters

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| id        | UUID | Yes      | Entry ID    |

#### Section 6: Response Schema (Success - 200)

```json theme={null}
{
  "status": "success",
  "data": {
    "id": "UUID",
    "title": "Science Project Submission",
    "description": "Submit solar system project with at least 5 planets",
    "diary_type": "homework",
    "priority": "high",
    "due_date": "2026-03-20",
    "status": "pending",
    "created_by": "Dr. Anjali Sharma",
    "attachment_url": "https://cdn.skole.com/diary/project-guide.pdf",
    "created_at": "2026-03-16T10:00:00.000Z"
  }
}
```

#### Section 8: Implementation Examples

**JavaScript:**

```javascript theme={null}
const getDiaryEntry = async (token, entryId) => {
  const response = await fetch(
    `https://api.skole.com/v1/parent-app/digital-diary/${entryId}`,
    {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  return (await response.json()).data;
};
```

#### Section 12: Response Summary Table

| Status | Scenario  | Error Code |
| ------ | --------- | ---------- |
| 200 ✅  | Success   | -          |
| 404 ❌  | Not found | NOT\_FOUND |

***

### PARENT-03: Mark Entry Completed

#### Section 1: Endpoint Summary

Parent marks a diary entry as completed for their child, updating status to reflect completion.

#### Section 2: HTTP Details

* **HTTP Method:** PUT
* **Endpoint URL:** `/parent-app/digital-diary/:id`
* **Authentication:** JWT (Parent)

#### Section 5: Request Body Schema

```json theme={null}
{
  "status*": "Enum: pending, completed"
}
```

#### Section 6: Response Schema (Success - 200)

```json theme={null}
{
  "status": "success",
  "message": "Entry marked as completed",
  "data": {
    "id": "UUID",
    "status": "completed",
    "completed_at": "2026-03-18T15:30:00.000Z"
  }
}
```

#### Section 8: Implementation Examples

**JavaScript:**

```javascript theme={null}
const markDiaryComplete = async (token, entryId) => {
  const response = await fetch(
    `https://api.skole.com/v1/parent-app/digital-diary/${entryId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ status: 'completed' })
    }
  );

  return (await response.json()).status === 'success';
};
```

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 200 ✅  | Success  | -          |

***

### PARENT-04: Upload Attachment

#### Section 1: Endpoint Summary

Allows parents to attach files (completion proof, photos) to diary entries.

#### Section 2: HTTP Details

* **HTTP Method:** POST
* **Endpoint URL:** `/parent-app/digital-diary/:id/attachments`
* **Content-Type:** `multipart/form-data`
* **Authentication:** JWT (Parent)

#### Section 5: Request Body Schema

```text theme={null}
Form Data:
- file: File (max 10MB, types: jpg, png, pdf, doc)
- description: String (optional)
```

#### Section 6: Response Schema (Success - 201)

```json theme={null}
{
  "status": "success",
  "message": "Attachment uploaded",
  "data": {
    "url": "https://cdn.skole.com/diary/attachments/file123.pdf",
    "filename": "project-proof.pdf",
    "size": 2048576
  }
}
```

#### Section 8: Implementation Examples

**JavaScript:**

```javascript theme={null}
const uploadDiaryAttachment = async (token, entryId, file) => {
  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch(
    `https://api.skole.com/v1/parent-app/digital-diary/${entryId}/attachments`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${token}` },
      body: formData
    }
  );

  return (await response.json()).data;
};
```

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 201 ✅  | Success  | -          |

***

### TEACH-01: List Teacher's Diary Entries

#### Section 1: Endpoint Summary

Teacher views all diary entries they created with filtering by type, priority, date.

#### Section 2: HTTP Details

* **HTTP Method:** GET
* **Endpoint URL:** `/teachers-app/digital-diary`
* **Authentication:** JWT (Staff)

#### Section 4: Query Parameters

| Parameter   | Type    | Required | Description            |
| ----------- | ------- | -------- | ---------------------- |
| diary\_type | String  | No       | Filter by type         |
| grade\_id   | UUID    | No       | Filter by target grade |
| status      | String  | No       | Filter by status       |
| take        | Integer | No       | Page size              |

#### Section 6: Response Schema (Success - 200)

```json theme={null}
{
  "status": "success",
  "data": {
    "entries": [
      {
        "id": "UUID",
        "title": "...",
        "grade": "10",
        "target_student": null,
        "diary_type": "homework",
        "due_date": "2026-03-18",
        "created_at": "2026-03-16T10:00:00.000Z"
      }
    ]
  }
}
```

#### Section 8: Implementation Examples

**JavaScript:**

```javascript theme={null}
const getMyDiaryEntries = async (token, filters = {}) => {
  const params = new URLSearchParams(filters);
  const response = await fetch(
    `https://api.skole.com/v1/teachers-app/digital-diary?${params}`,
    {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  return (await response.json()).data.entries;
};
```

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 200 ✅  | Success  | -          |

***

### TEACH-02: Get Entry Detail

#### Section 1: Endpoint Summary

Fetch complete entry details for viewing/editing.

#### Section 2: HTTP Details

* **HTTP Method:** GET
* **Endpoint URL:** `/teachers-app/digital-diary/:id`
* **Authentication:** JWT (Staff)

#### Section 6: Response Schema (Success - 200)

```json theme={null}
{
  "status": "success",
  "data": {
    "id": "UUID",
    "title": "...",
    "description": "...",
    "diary_type": "homework",
    "priority": "high",
    "due_date": "2026-03-18",
    "target_grade": "10",
    "target_student": null
  }
}
```

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 200 ✅  | Success  | -          |

***

### TEACH-03: Create Diary Entry

#### Section 1: Endpoint Summary

Teacher creates new diary entry (homework, classwork, note, reminder) for grade or specific student.

#### Section 2: HTTP Details

* **HTTP Method:** POST
* **Endpoint URL:** `/teachers-app/digital-diary`
* **Authentication:** JWT (Staff)

#### Section 5: Request Body Schema

```json theme={null}
{
  "title*": "String",
  "description*": "String",
  "diary_type*": "Enum: homework, classwork, note, reminder",
  "grade_id*": "UUID",
  "student_id": "UUID (optional, for specific student)",
  "due_date*": "Date",
  "priority*": "Enum: low, medium, high",
  "attachment_url": "String (optional)"
}
```

#### Section 6: Response Schema (Success - 201)

```json theme={null}
{
  "status": "success",
  "message": "Entry created",
  "data": {
    "id": "UUID",
    "created_at": "2026-03-16T10:00:00.000Z"
  }
}
```

#### Section 7: Error Responses

**400 - Invalid Type**

```json theme={null}
{
  "status": "error",
  "code": "INVALID_TYPE",
  "message": "diary_type must be homework, classwork, note, or reminder"
}
```

#### Section 8: Implementation Examples

**JavaScript:**

```javascript theme={null}
const createDiaryEntry = async (token, entry) => {
  const response = await fetch(
    'https://api.skole.com/v1/teachers-app/digital-diary',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(entry)
    }
  );

  const data = await response.json();
  if (data.status === 'success') return data.data.id;
  throw new Error(data.message);
};

// Usage
const entryId = await createDiaryEntry(token, {
  title: 'Math Homework',
  description: 'Complete exercises 1-20',
  diary_type: 'homework',
  grade_id: 'uuid',
  due_date: '2026-03-18',
  priority: 'high'
});
```

#### Section 12: Response Summary Table

| Status | Scenario | Error Code    |
| ------ | -------- | ------------- |
| 201 ✅  | Success  | -             |
| 400 ❌  | Invalid  | INVALID\_TYPE |

***

### TEACH-04: Update Entry

#### Section 1: Endpoint Summary

Teacher updates diary entry contents, deadline, or priority.

#### Section 2: HTTP Details

* **HTTP Method:** PUT
* **Endpoint URL:** `/teachers-app/digital-diary/:id`
* **Authentication:** JWT (Staff)

#### Section 5: Request Body Schema

```json theme={null}
{
  "title": "String",
  "description": "String",
  "due_date": "Date",
  "priority": "Enum",
  "attachment_url": "String"
}
```

#### Section 6: Response Schema (Success - 200)

```json theme={null}
{
  "status": "success",
  "message": "Entry updated"
}
```

#### Section 8: Implementation Examples

**JavaScript:**

```javascript theme={null}
const updateDiaryEntry = async (token, entryId, updates) => {
  const response = await fetch(
    `https://api.skole.com/v1/teachers-app/digital-diary/${entryId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

  return (await response.json()).status === 'success';
};
```

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 200 ✅  | Success  | -          |

***

### TEACH-05: Delete Entry

#### Section 1: Endpoint Summary

Teacher soft-deletes a diary entry (hidden from parents but retained in database for audit).

#### Section 2: HTTP Details

* **HTTP Method:** DELETE
* **Endpoint URL:** `/teachers-app/digital-diary/:id`
* **Authentication:** JWT (Staff)

#### Section 6: Response Schema (Success - 200)

```json theme={null}
{
  "status": "success",
  "message": "Entry deleted"
}
```

#### Section 8: Implementation Examples

**JavaScript:**

```javascript theme={null}
const deleteDiaryEntry = async (token, entryId) => {
  const response = await fetch(
    `https://api.skole.com/v1/teachers-app/digital-diary/${entryId}`,
    {
      method: 'DELETE',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  return (await response.json()).status === 'success';
};
```

#### Section 9: Database Context

Sets `deleted_status = 1`, entry hidden from all consumer APIs

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 200 ✅  | Success  | -          |

***

### ADMIN-01: List All Entries (Web App)

#### Section 1: Endpoint Summary

Admin views all diary entries across school with global filters.

#### Section 2: HTTP Details

* **HTTP Method:** GET
* **Endpoint URL:** `/web-app/digital-diary`
* **Authentication:** JWT (Admin)

#### Section 4: Query Parameters

| Parameter        | Type    | Required | Description          |
| ---------------- | ------- | -------- | -------------------- |
| grade\_id        | UUID    | No       | Filter by grade      |
| created\_by      | UUID    | No       | Filter by teacher    |
| diary\_type      | String  | No       | Filter by type       |
| include\_deleted | Boolean | No       | Include soft-deleted |

#### Section 6: Response Schema (Success - 200)

```json theme={null}
{
  "status": "success",
  "data": {
    "entries": [...],
    "pagination": {
      "total": 450,
      "take": 20
    }
  }
}
```

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 200 ✅  | Success  | -          |

***

### ADMIN-02: Get Entry Detail (Web App)

#### Section 1: Endpoint Summary

Admin views complete diary entry details including creator and target audience.

#### Section 2: HTTP Details

* **HTTP Method:** GET
* **Endpoint URL:** `/web-app/digital-diary/:id`
* **Authentication:** JWT (Admin)

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 200 ✅  | Success  | -          |

***

### ADMIN-03: Create Entry (Web App)

#### Section 1: Endpoint Summary

Admin creates diary entries on behalf of staff (for system announcements or corrections).

#### Section 2: HTTP Details

* **HTTP Method:** POST
* **Endpoint URL:** `/web-app/digital-diary`
* **Authentication:** JWT (Admin)

#### Section 5: Request Body Schema

```json theme={null}
{
  "title*": "String",
  "description*": "String",
  "diary_type*": "Enum",
  "grade_id*": "UUID",
  "created_by*": "UUID (staff_id or admin_id)",
  "due_date*": "Date",
  "priority": "Enum"
}
```

#### Section 6: Response Schema (Success - 201)

```json theme={null}
{
  "status": "success",
  "message": "Entry created",
  "data": {"id": "UUID"}
}
```

#### Section 12: Response Summary Table

| Status | Scenario | Error Code |
| ------ | -------- | ---------- |
| 201 ✅  | Success  | -          |

***

## 12. Summary Table: All 12 Digital Diary Endpoints

| ID        | Endpoint                                    | Method | Description    | Status       |
| --------- | ------------------------------------------- | ------ | -------------- | ------------ |
| PARENT-01 | `/parent-app/digital-diary`                 | GET    | List entries   | ✅ Documented |
| PARENT-02 | `/parent-app/digital-diary/:id`             | GET    | Entry detail   | ✅ Documented |
| PARENT-03 | `/parent-app/digital-diary/:id`             | PUT    | Mark completed | ✅ Documented |
| PARENT-04 | `/parent-app/digital-diary/:id/attachments` | POST   | Upload file    | ✅ Documented |
| TEACH-01  | `/teachers-app/digital-diary`               | GET    | List entries   | ✅ Documented |
| TEACH-02  | `/teachers-app/digital-diary/:id`           | GET    | Entry detail   | ✅ Documented |
| TEACH-03  | `/teachers-app/digital-diary`               | POST   | Create entry   | ✅ Documented |
| TEACH-04  | `/teachers-app/digital-diary/:id`           | PUT    | Update entry   | ✅ Documented |
| TEACH-05  | `/teachers-app/digital-diary/:id`           | DELETE | Delete entry   | ✅ Documented |
| ADMIN-01  | `/web-app/digital-diary`                    | GET    | List all       | ✅ Documented |
| ADMIN-02  | `/web-app/digital-diary/:id`                | GET    | Entry detail   | ✅ Documented |
| ADMIN-03  | `/web-app/digital-diary`                    | POST   | Create entry   | ✅ Documented |