# Parent Workflows — Figma Production Specs

---

## 1. PARENT SELF-REGISTRATION WORKFLOW

### Complete Journey

```
[Public Landing: /register]
    │
    │ Click "Register as Parent"
    ▼
[/register/parent]
    │
    │ Parent fills form:
    │ ├── Full name
    │ ├── Email address
    │ ├── Phone number
    │ ├── Password (min 8 chars)
    │ ├── Confirm password
    │ ├── ☐ Accept Terms of Service
    │ └── ☐ Accept Payment Responsibility
    │
    │ On submit:
    │ ├── User created with role: parent
    │ ├── policy_acceptances records created (2)
    │ ├── IP address + timestamp logged
    │ └── Redirect to /register/add-ward
    ▼
[/register/add-ward]
    │
    │ Parent fills:
    │ ├── Child's full name
    │ ├── Date of birth
    │ ├── Gender
    │ └── Class (select from active classes)
    │
    │ On submit:
    │ ├── CredentialGeneratorService runs
    │ ├── Student ID generated: RP-2026-XXXXX
    │ ├── Temporary password generated
    │ ├── Student user created (role: student)
    │ ├── parent_student pivot: is_primary_guardian = TRUE
    │ ├── credential_delivery_logs record created
    │ └── Redirect to credential display
    ▼
[Credential Display Screen]
    │
    │ Shows:
    │ ├── Student Name
    │ ├── Student ID: RP-2026-00001 (copyable)
    │ ├── Temporary Password: •••••••• (masked, toggle to show)
    │ │
    │ │ Actions:
    │ ├── [Copy Credentials] → clipboard
    │ ├── [Download PDF] → DomPDF generation
    │ ├── [Email to Student] → sends to entered email
    │ │
    │ Warning: "Please save these credentials.
    │          Temporary password expires on first login."
    │
    │ ├── [+ Add Another Ward] → back to /register/add-ward
    │ └── [Go to Dashboard] → enters parent portal (PAR-01)
    ▼
[PAR-01: Parent Command Center]
```

### Registration Form Validation

| Field | Validation | Error Message |
|-------|-----------|---------------|
| Full name | Required, 2-100 chars | "Please enter your full name" |
| Email | Required, valid format, unique | "Email already registered" |
| Phone | Required, valid Ghana format | "Please enter a valid phone number" |
| Password | Required, min 8 chars | "Password must be at least 8 characters" |
| Confirm password | Must match password | "Passwords do not match" |
| T&C checkbox | Required | "You must accept the Terms of Service" |
| Payment checkbox | Required | "You must accept Payment Responsibility" |

### Add Ward Form Validation

| Field | Validation | Error Message |
|-------|-----------|---------------|
| Child name | Required, 2-100 chars | "Please enter child's full name" |
| DOB | Required, age 4-18 | "Student must be between 4 and 18 years" |
| Gender | Required | "Please select gender" |
| Class | Required, active class | "Please select a class" |

---

## 2. ACTION ITEM WORKFLOW

### Parent Action Item Lifecycle

```
Teacher creates action item (TCH-20)
    │
    │ Parent receives notification:
    │ ├── In-app notification
    │ ├── Email notification (if enabled)
    │ └── SMS (if urgent + enabled)
    ▼
[PAR-06: Action Items List]
    │
    │ Status: Pending
    │ "Not yet acknowledged"
    │
    │ Parent clicks [Acknowledge]
    │ → Acknowledgement timestamp recorded
    │ → Status: Pending (acknowledged)
    ▼
[PAR-07: Action Item Detail]
    │
    │ Parent reviews details:
    │ ├── Description
    │ ├── Due date
    │ ├── Related teacher remarks
    │ └── Activity log
    │
    │ Parent takes action:
    │ ├── Reviews homework with child
    │ ├── Signs practice log
    │ └── etc.
    │
    │ Parent clicks [Mark Complete]
    │ → Confirmation modal
    ▼
[Confirmation Modal]
    │
    │ "Mark this action item as complete?"
    │ "This will notify Dr. Mensah."
    │
    │ [Cancel]  [Mark Complete]
    │
    │ On confirm:
    │ ├── Status → Completed
    │ ├── Completed timestamp recorded
    │ ├── Notification sent to teacher
    │ └── Activity log updated
    ▼
[PAR-06: Updated list — item shows ✓ Completed]
```

### Action Item Statuses

| Status | Icon | Color | Description |
|--------|------|-------|-------------|
| `pending` | ○ | grey | Not yet acknowledged |
| `in_progress` | ⏳ | amber | Acknowledged, not yet completed |
| `completed` | ✓ | green | Marked complete by parent |
| `overdue` | ⚠ | red | Past due date, not completed |

### Overdue Action Item Behavior

```
When action item passes due date:
├── Status badge changes to "Overdue" (red)
├── Row highlighted: BG rgba(220,38,38,0.05)
├── Automatic reminder sent to parent
├── Teacher notified: "Action item overdue"
├── Appears at top of list (sorted by urgency)
└── Dashboard KPI card shows overdue count
```

### Parent Acknowledgement Flow

```
Action Item Created
    │
    ├── Auto-notification sent
    │
    ├── Parent views item (PAR-07)
    │   → "viewed" event logged
    │
    ├── Parent clicks [Acknowledge]
    │   → acknowledged_at timestamp set
    │   → acknowledged_by_ip logged
    │   → Status: pending → in_progress
    │
    └── Parent completes action
        → completed_at timestamp set
        → Status: in_progress → completed
```

---

## 3. INVOICE PAYMENT WORKFLOW

### End-to-End Payment Journey

```
Admin creates fee structures (ADM-21)
    │
Admin assigns fees to students (ADM-22)
    │
InvoiceGeneratorService generates invoices
    │
Invoice sent to primary guardian
    ├── Email notification with invoice PDF
    ├── In-app notification
    └── Dashboard KPI updated
    ▼
[PAR-01: Dashboard shows outstanding amount]
    │
    │ Click "Pay Now"
    ▼
[PAR-08: Invoices List]
    │
    │ Click invoice card
    ▼
[PAR-09: Invoice Detail]
    │
    │ Review line items
    │ Confirm amount
    │ Click "Pay Now"
    ▼
[PAR-10: Payment Flow]
    │
    │ Select payment method
    │ Enter details
    │ Submit
    │
    │ Paystack processes payment
    │
    ├── Success:
    │   │
    │   │ Backend:
    │   │ ├── Payment record created
    │   │ ├── Invoice status updated
    │   │ ├── Receipt generated (DomPDF)
    │   │ ├── Receipt emailed to parent
    │   │ └── Admin notified
    │   │
    │   ▼
    │   [PAR-11: Receipt Download]
    │       │
    │       ├── [Download PDF]
    │       ├── [Email Receipt]
    │       └── [Return to Dashboard]
    │
    └── Failure:
        │
        └── Error message displayed
            [Retry] or [Change Method]
```

### Partial Payment Flow

```
Invoice total: ₵ 1,200
Payment 1: ₵ 500 (successful)
    │
    │ Invoice status → partially_paid
    │ Balance: ₵ 700
    │
    ▼
Parent returns later
    │
    │ Dashboard shows: "₵ 700 remaining on INV-2026-0042"
    │
    ▼
Payment 2: ₵ 700 (successful)
    │
    │ Invoice status → paid
    │ Balance: ₵ 0
    │
    ▼
Receipt issued for ₵ 700
Full payment history visible on PAR-09
```

---

## 4. CREDENTIAL MANAGEMENT WORKFLOW

### Credential Lifecycle

```
Registration (parent creates ward)
    │
    │ Credentials generated:
    │ ├── Student ID: RP-2026-XXXXX
    │ ├── Temporary password: random 8-char
    │ └── Logged to credential_delivery_logs
    │
    ├── Displayed on screen (PAR-16 equivalent)
    ├── Emailed to parent
    └── Downloaded as PDF
    │
    ▼
First Login (student)
    │
    │ System forces password change:
    │ ├── "Your temporary password has expired"
    │ ├── "Please create a new password"
    │ └── New password: min 8 chars, confirmed
    │
    ▼
Ongoing Access
    │
    │ Parent can (via PAR-16):
    │ ├── View student ID (always visible)
    │ ├── View temporary password (masked, toggle)
    │ ├── Copy credentials to clipboard
    │ ├── Download credentials PDF
    │ ├── Email credentials to student
    │ └── Resend credentials (re-generates temp password)
    │
    └── Each action logged to credential_delivery_logs
```

### Credential Delivery Log Display

```
┌──────────────────────────────────────────────────┐
│  Delivery History                                │
│                                                  │
│  Jun 10, 2026, 2:15 PM — Created during         │
│    registration                                  │
│    IP: 192.168.1.1                               │
│                                                  │
│  Jun 10, 2026, 2:15 PM — Emailed to parent      │
│    kofi@example.com                              │
│                                                  │
│  Jun 12, 2026, 10:30 AM — PDF downloaded        │
│    IP: 192.168.1.1                               │
│                                                  │
│  Jun 15, 2026, 3:45 PM — Credentials resent     │
│    New temporary password generated              │
│    IP: 192.168.1.1                               │
└──────────────────────────────────────────────────┘
```

---

## 5. MESSAGING WORKFLOW

### Parent-Teacher Communication

```
Parent initiates message (PAR-12)
    │
    │ Compose:
    │ ├── To: [Select teacher] (from child's teachers)
    │ ├── Subject: [Auto-populated or custom]
    │ └── Message: [Text content]
    │
    │ On send:
    │ ├── Message record created
    │ ├── Conversation created (or existing used)
    │ ├── Teacher notified (in-app + email)
    │ └── Message appears in chat
    │
    ▼
Teacher responds (TCH-24)
    │
    │ Response appears in parent's PAR-12
    │ Parent notified (in-app + email)
    │
    ▼
Conversation continues
    │
    ├── Real-time updates (polling or WebSocket)
    ├── Message read receipts
    └── File attachments (optional)
```

### Message Thread Display

```
┌──────────────────────────────────────────────────┐
│  Conversation with Dr. Mensah                    │
│  Mathematics — Amara Asante                      │
├──────────────────────────────────────────────────┤
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Dr. Mensah                    Jun 12, 9AM │   │
│  │                                          │   │
│  │ Hello Kofi, I wanted to discuss Amara's  │   │
│  │ progress in algebra. She's been doing    │   │
│  │ much better since the tutoring sessions. │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│       ┌──────────────────────────────────────┐   │
│       │ You                    Jun 12, 10:30AM│   │
│       │                                      │   │
│       │ Thank you, Dr. Mensah. We've been    │   │
│       │ practicing at home too.              │   │
│       └──────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Dr. Mensah                    Jun 12, 11AM │   │
│  │                                          │   │
│  │ That's great to hear! I'll keep you      │   │
│  │ updated on her progress.                 │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
├──────────────────────────────────────────────────┤
│  [Type a message...]                    [Send]   │
│  [📎 Attachment]                                 │
└──────────────────────────────────────────────────┘
```

---

## 6. NOTIFICATION WORKFLOW

### Parent Notification Categories

| Category | Triggers | Default Channels |
|----------|----------|-----------------|
| Financial | Invoice created, payment confirmed, invoice overdue | In-App, Email, SMS |
| Attendance | Child attendance < 80%, absence recorded | In-App, Email |
| Academic | Grades published, exam results, assignment graded | In-App, Email |
| Action Items | New item assigned, reminder, overdue | In-App, Email |
| Messages | New message from teacher | In-App |
| System | School announcements, policy updates | In-App |
| Interventions | New intervention created, progress update | In-App, Email |

### Notification Center (PAR-13)

```
┌──────────────────────────────────────────────────┐
│  Notifications                         [Mark All Read] │
├──────────────────────────────────────────────────┤
│                                                  │
│  [All] [Financial] [Academic] [Action Items]     │
│                                                  │
│  ● Invoice INV-2026-0042 is overdue              │
│    Financial • 2 hours ago                       │
│                                                  │
│  ● Amara scored 85% on Math Quiz                 │
│    Academic • Yesterday                          │
│                                                  │
│  ○ Payment of ₵ 500 confirmed                    │
│    Financial • Jun 14                            │
│    ✓ Read                                        │
│                                                  │
│  ○ New message from Dr. Mensah                   │
│    Messages • Jun 12                             │
│    ✓ Read                                        │
│                                                  │
│  ● Action item: Review homework — overdue        │
│    Action Items • Jun 11                         │
│                                                  │
└──────────────────────────────────────────────────┘
```

### Notification Preferences (PAR-13)

```
┌──────────────────────────────────────────────────┐
│  Notification Preferences                        │
├──────────────────────────────────────────────────┤
│                                                  │
│  In-App   Email    SMS     Category              │
│  ─────    ─────    ───     ──────                │
│  [ON]     [ON]     [ON]    Financial / Invoices  │
│  [ON]     [ON]     [ON]    Attendance Warnings   │
│  [ON]     [ON]     [OFF]   Academic Updates      │
│  [ON]     [ON]     [OFF]   Action Items          │
│  [ON]     [OFF]    [OFF]   Teacher Messages      │
│  [ON]     [OFF]    [OFF]   System Announcements  │
│  [ON]     [OFF]    [OFF]   Policy Updates        │
│                                                  │
│  Note: In-App is always ON and cannot be toggled │
│                                                  │
│  ─────────────────────────────────────────────   │
│                                                  │
│  Digest Settings                                 │
│  Frequency: [Real-time ▾]                        │
│  Quiet hours: [10:00 PM] to [7:00 AM]           │
│                                                  │
│  [Save Preferences]                              │
│                                                  │
└──────────────────────────────────────────────────┘
```

---

## 7. POLICY ACCEPTANCE WORKFLOW

### Policy Types

| Policy | When Required | Can Revoke |
|--------|--------------|------------|
| Terms of Service | Registration | No |
| Payment Responsibility | Registration | No |
| Data Privacy | Registration | No |
| Media Consent | Registration | Yes |
| Code of Conduct | Registration | No |

### Acceptance Flow

```
Registration:
    │
    │ Checkboxes for T&C + Payment Responsibility
    │ Both required to proceed
    │
    │ On accept:
    │ ├── policy_acceptances record created
    │ ├── IP address logged
    │ ├── Timestamp logged
    │ └── Cryptographic hash generated
    │
    ▼
[PAR-15: Policy Acceptances]
    │
    │ Shows all accepted policies
    │ With dates and IP addresses
    │
    │ New policies requiring acceptance:
    │ ├── Banner at top: "New policy requires your acceptance"
    │ ├── [Review & Accept] button
    │ └── Modal with full policy text
    │
    └── Acceptance recorded with same audit trail
```

---

## 8. PARENT PORTAL RESPONSIVE BEHAVIOR

### Mobile Bottom Navigation

```
┌─────────────────────┐
│                     │
│  (Page content)     │
│                     │
├─────────────────────┤
│ 🏠   📋   💰   💬   │
│ Dash  Act  Inv  Msg │
└─────────────────────┘
```

### Mobile-Specific Behaviors

| Feature | Desktop | Mobile |
|---------|---------|--------|
| Sidebar | Expanded (260px) | Hidden (bottom nav) |
| Child switcher | Full display with stats | Avatar tap → dropdown |
| KPI cards | 4 across | 2×2 grid |
| Widgets | 2-column layout | Stacked |
| Invoice detail | Centered 720px | Full-width |
| Payment flow | Centered 600px | Full-width |
| Messages | 320px + chat | Full-screen list → chat |
| Credential card | Full display | Stacked, scrollable |

### Mobile Touch Interactions

- Action item "Done" button: Long-press to confirm
- Payment method tabs: Horizontal swipe
- Invoice cards: Tap to expand details
- Message input: Auto-expand textarea on focus
- Child switcher: Tap avatar area to open