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

# Profile, Notifications & Dashboard

> Consolidated view of user profile data, real-time push notification history, and the home dashboard overview.

## 1. API Purpose

This consolidated module handles the core "Home" experience. It manages personal profile data for parents and their children, tracks the history of push notifications sent to devices, and powers the summary dashboard that surfaces critical info at a glance.

***

## 2. Endpoint Definition

| Method | Route                                     | Auth      | Description                               |
| ------ | ----------------------------------------- | --------- | ----------------------------------------- |
| GET    | `/parent-app/profile`                     | 🔐 JWT    | View parent/family profile                |
| PUT    | `/parent-app/auth/device-info`            | 🔐 JWT    | Update device info (FCM)                  |
| GET    | `/teachers-app/notifications`             | 🔐 JWT    | View staff notification history           |
| POST   | `/teachers-app/notifications/mark-read`   | 🔐 JWT    | Mark push history as read                 |
| GET    | `/teachers-app/notifications/status`      | 🔐 JWT    | Diagnostic: Notification subsystem status |
| POST   | `/teachers-app/notifications/test-parent` | 🔐 JWT    | Diagnostic: Trigger test notification     |
| GET    | `/web-app/dashboard`                      | 🔐 JWT    | Admin: School overview stats              |
| GET    | `/web-app/health`                         | 🔓 Public | Diagnostic: Web App API health            |

***

## 3. Authentication Flow

Standard JWT validation.

* **Profile:** Data is largely served from the JWT payload itself or by querying the `parent_details` table using the `sub` ID.
* **Notifications:** Access is limited to notifications specifically sent to the user's ID/skole\_id.

***

## 4. Request Structure

#### GET /parent-app/profile

**Headers:**

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

#### PUT /parent-app/auth/device-info

**Request Body:**

```json theme={null}
{
  "fcm_token": "fcm_token_xyz",
  "device_name": "iPhone 15 Pro"
}
```

#### GET /teachers-app/notifications/status

**Headers:**

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

#### POST /teachers-app/notifications/test-parent

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "parent_id": 1,
  "title": "🔔 Test Notification",
  "body": "This is a test notification from the diagnostic endpoint.",
  "data": { "key": "value" }
}
```

#### GET /web-app/health

**Headers:**

```http theme={null}
Accept: application/json
```

***

## 5. Response Structure

#### Success: Profile View (200 OK)

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

```json theme={null}
{
  "success": true,
  "data": {
    "parent": { "id": 1, "name": "Rajesh Kumar" },
    "children": [ { "id": 45, "name": "Aarav" } ]
  }
}
```

#### Success: Device Info Updated (200 OK)

**Route:** `PUT /parent-app/auth/device-info`

```json theme={null}
{
  "success": true,
  "message": "FCM token successfully registered"
}
```

#### Success: Notification History (200 OK)

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

```json theme={null}
{
  "success": true,
  "data": [
    { "id": 101, "title": "New Assignment", "status": "read" }
  ]
}
```

#### Success: Notifications Marked Read (200 OK)

**Route:** `POST /teachers-app/notifications/mark-read`

```json theme={null}
{
  "success": true,
  "message": "Notification counts reset"
}
```

#### Success: Diagnostic Status (200 OK)

**Route:** `GET /teachers-app/notifications/status`

```json theme={null}
{
  "success": true,
  "data": { "initialized": true, "provider": "fire-base" }
}
```

#### Success: Test Push Triggered (200 OK)

**Route:** `POST /teachers-app/notifications/test-parent`

```json theme={null}
{
  "success": true,
  "message": "Notification trigger sequence initiated"
}
```

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

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

```json theme={null}
{
  "success": true,
  "data": {
    "total_students": 1200,
    "active_teachers": 45,
    "pending_requests": 12
  }
}
```

#### Success: Health Status (200 OK)

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

```json theme={null}
{
  "success": true,
  "message": "Web App API is running",
  "module": "web-app"
}
```

***

## 6. Error Responses

| HTTP Code | Description                            |
| --------- | -------------------------------------- |
| 401       | Unauthorized: Token expired or invalid |
| 500       | Database connection error              |

***

## 7. Security Considerations

* **Isolation:** Dashboard stats are strictly aggregated within the `skole_id` context.
* **Privacy:** Child profiles include medical ailments; these are only visible to the linked parent and assigned class teacher.

***

## 8. Token Usage

```http theme={null}
GET /teachers-app/notifications
Authorization: Bearer <TOKEN>
```

***

## 9. Token Refresh

N/A.

***

## 10. Logout / Session Invalidation

Logout is handled here for the parent app, which clears the `fcm_token` from the `parent_devices` table to prevent ghost notifications.

***

## 11. Usage Example (cURL)

```bash theme={null}
curl -H "Authorization: Bearer <TOKEN>" \
"http://localhost:3000/web-app/dashboard?skole_id=SKL001"
```

***

## 12. Notes / Special Behaviors

* **FCM Registration:** For parents, the push notification system relies on tokens registered during the `/auth-verification` flow.
* **Dashboard Aggregation:** The dashboard API performs multiple internal counts (diary, attendance, write-to) to provide a single JSON response for the home screen.
* **Fees Placeholder:** The Fees UI exists as a planned feature; the current API serves a "Coming Soon" or empty state placeholder.