# ParentApi Module — Architecture Map

> **Last updated:** 2026-06-13
> **Status:** Living document

---

## 1. Purpose & Responsibilities

The ParentApi module provides the **mobile app REST API for parents/guardians**. It enables:

- Viewing linked children (players) with per-child permission flags
- Child dashboard (attendance, evaluations, medical, financials, achievements)
- Parent notification feed (in-app + push)
- Profile management
- Push token registration

Authorization is **identity + permission-based**: parents only see children linked via `parent_player_links`, with granular `can_view_*` flags per child.

---

## 2. Directory & File Structure

```
app/Modules/ParentApi/
├── bootstrap.php                              # Event listeners for parent notifications
├── ApiRoutes.php                              # 16 API routes
├── Controllers/
│   └── Api/
│       ├── ChildrenController.php             # Children list + detailed views per permission
│       ├── DeviceController.php               # Push token registration
│       ├── NotificationController.php         # Notification feed + mark read
│       └── ProfileController.php              # Parent profile view/update
```

---

## 3. Routes (16 total — all under `/api/v1/parent/`)

All routes use `['cors', 'parent_auth']` middleware.

| Method | Path | Purpose |
|--------|------|---------|
| GET | /api/v1/parent/profile | Parent profile |
| PUT | /api/v1/parent/profile | Update profile |
| GET | /api/v1/parent/children | Linked players list |
| GET | /api/v1/parent/children/{id}/dashboard | Full child dashboard |
| GET | /api/v1/parent/children/{id}/attendance | Attendance history |
| GET | /api/v1/parent/children/{id}/evaluations | Evaluations |
| GET | /api/v1/parent/children/{id}/medical | Medical records + injuries |
| GET | /api/v1/parent/children/{id}/financials | Subscriptions, fines, installments, payments |
| GET | /api/v1/parent/children/{id}/achievements | Badges + points |
| GET | /api/v1/parent/notifications | Notification feed |
| POST | /api/v1/parent/notifications/{id}/read | Mark single read |
| POST | /api/v1/parent/notifications/read-all | Mark all read |
| GET | /api/v1/parent/notifications/unread-count | Badge count |
| POST | /api/v1/parent/device | Register push token |
| DELETE | /api/v1/parent/device | Clear push token |

---

## 4. Permission Model

Access controlled via `parent_player_links` table:
- `can_view_attendance` — gates /attendance endpoint
- `can_view_evaluations` — gates /evaluations endpoint
- `can_view_medical` — gates /medical endpoint
- `can_view_financials` — gates /financials endpoint
- `can_approve_group_change` — future use

Parent can always see: child list, basic profile, groups, achievements.

---

## 5. Events Consumed (bootstrap.php)

| Event | Notification Type | Message |
|-------|-------------------|---------|
| player.enrolled | enrollment | "تم تسجيل ابنكم في مجموعة X" |
| player.evaluation_completed | evaluation | "تم تقييم ابنكم" |
| facility.attendance_absent | attendance | "تم تسجيل غياب ابنكم" |
| player.medical_expiring | medical | "الكشف الطبي لابنكم سينتهي قريباً" |

---

## 6. Database Tables Read

| Table | Purpose |
|-------|---------|
| parent_accounts | Profile |
| parent_player_links | Access control |
| players | Child info |
| session_attendance + training_sessions | Attendance |
| player_evaluations | Evaluations |
| player_medical_records | Medical |
| player_injuries | Injuries |
| activity_subscriptions | Subscriptions |
| fines | Fines |
| installment_plans + installment_schedule | Installments |
| payments | Payment history |
| player_achievements + achievement_definitions | Achievements |
| group_memberships + training_groups | Active groups |
| parent_notifications_log | Notifications |

---

## 7. Cross-Module Dependencies

| Dependency | Direction |
|-----------|-----------|
| ParentAuth | ParentApi requires valid parent token |
| PlayerAffairs | Reads player data |
| SportsActivity | Reads attendance, groups |
| Subscriptions | Reads activity_subscriptions |
| Fines | Reads fines |
| Installments | Reads installment plans |
| Payments | Reads payment history |
| Achievements | Reads achievements |
| PushNotificationService | Sends push on events |
