Skip to main content

​
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

MethodRouteAuthDescription
GET/parent-app/profile🔐 JWTView parent/family profile
PUT/parent-app/auth/device-info🔐 JWTUpdate device info (FCM)
GET/teachers-app/notifications🔐 JWTView staff notification history
POST/teachers-app/notifications/mark-read🔐 JWTMark push history as read
GET/teachers-app/notifications/status🔐 JWTDiagnostic: Notification subsystem status
POST/teachers-app/notifications/test-parent🔐 JWTDiagnostic: Trigger test notification
GET/web-app/dashboard🔐 JWTAdmin: School overview stats
GET/web-app/health🔓 PublicDiagnostic: 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: 
Authorization: Bearer <TOKEN>

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

Request Body: 
{
  "fcm_token": "fcm_token_xyz",
  "device_name": "iPhone 15 Pro"
}

​
GET /teachers-app/notifications/status

Headers: 
Authorization: Bearer <TOKEN>

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

Request Body: 
{
  "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: 
Accept: application/json

​
5. Response Structure

​
Success: Profile View (200 OK)

Route: GET /parent-app/profile 
{
  "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 
{
  "success": true,
  "message": "FCM token successfully registered"
}

​
Success: Notification History (200 OK)

Route: GET /teachers-app/notifications 
{
  "success": true,
  "data": [
    { "id": 101, "title": "New Assignment", "status": "read" }
  ]
}

​
Success: Notifications Marked Read (200 OK)

Route: POST /teachers-app/notifications/mark-read 
{
  "success": true,
  "message": "Notification counts reset"
}

​
Success: Diagnostic Status (200 OK)

Route: GET /teachers-app/notifications/status 
{
  "success": true,
  "data": { "initialized": true, "provider": "fire-base" }
}

​
Success: Test Push Triggered (200 OK)

Route: POST /teachers-app/notifications/test-parent 
{
  "success": true,
  "message": "Notification trigger sequence initiated"
}

​
Success: Admin Dashboard Stats (200 OK)

Route: GET /web-app/dashboard 
{
  "success": true,
  "data": {
    "total_students": 1200,
    "active_teachers": 45,
    "pending_requests": 12
  }
}

​
Success: Health Status (200 OK)

Route: GET /web-app/health 
{
  "success": true,
  "message": "Web App API is running",
  "module": "web-app"
}

​
6. Error Responses

HTTP CodeDescription
401Unauthorized: Token expired or invalid
500Database 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

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)

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.