> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleverschool.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Pupil Portal

> Workflows, Lifecycles & Integration

## End-to-End Pupil Engagement Lifecycle

The **Pupil Portal** links student identity, extracurricular club participation, live attendance verification, and school-wide analytics into a seamless operational lifecycle.

```mermaid theme={null}
flowchart TD
    subgraph IngestionPhase["Phase 1: Identity & Roster Provisioning"]
        I1["1. MIS Roster Ingested<br/><i>(Wonde Sync / CSV Bulk Upload)</i>"]
        I2["2. Student Accounts Created<br/><i>(Name, Form, Year, House, Email)</i>"]
        I3["3. Authentication Configured<br/><i>(Google / Microsoft SSO or Verified Email)</i>"]
        I1 --> I2 --> I3
    end

    subgraph ClubPhase["Phase 2: Extracurricular Scheduling & Enrolment"]
        C1["4. Club Leader creates Meeting / Fixture<br/><i>(Date, Time, Location, Opponent)</i>"]
        C2["5. System generates Unique Meeting ULID & QR Code"]
        C3["6. Meeting appears on Student's /pupil Dashboard"]
        C1 --> C2 --> C3
    end

    subgraph CheckInPhase["Phase 3: Live Session Check-In"]
        K1["7. Student scans QR Code at start of session"]
        K2{"Same Day & Active Member?"}
        K3["8. Toggle 'Mark as attended' ➔ Instant Save"]
        K4["Attendance Logged in Database Pivot"]
        K5["Leader / Pastoral Review required"]
        K1 --> K2
        K2 -->|Yes| K3 --> K4
        K2 -->|No / Past / Future| K5
    end

    subgraph GamificationPhase["Phase 4: Recognition & Gamification"]
        G1["9. Attendance threshold reached"]
        G2["10. Achievement Badge awarded"]
        G3["11. Badge displayed on Pupil Profile Header"]
        K4 --> G1 --> G2 --> G3
    end

    subgraph AnalyticsPhase["Phase 5: Pastoral Analytics & House Standing"]
        A1["12. Attendance aggregated across Houses & Years"]
        A2["13. Dynamic charts updated at /pupil/stats"]
        A3["14. Pastoral team reviews cohort engagement & house points"]
        K4 --> A1 --> A2 --> A3
    end

    IngestionPhase --> ClubPhase
    ClubPhase --> CheckInPhase
```

***

## 1. Pupil Identity Provisioning & MIS Synchronisation

Maintaining accurate student rosters is vital for attendance integrity and secure single sign-on:

### Automated Wonde Sync Pipeline

For schools connected via Wonde, the automated synchronisation command (`php artisan sync:wonde-pupils`) executes on a nightly schedule:

1. **Roster Comparison**: Evaluates current student enrolments against local Cleverschool records.
2. **Attribute Refresh**: Updates year group rollovers, form tutor allocations, and house assignments.
3. **Avatar Processing**: Securely fetches and processes student profile photos, generating optimised PNG thumbnails cached within the tenant's public storage disk.
4. **Soft Deletions**: Students who leave the school roll are flagged as archived, preserving their historical club attendance and provision records while revoking active login privileges.

### CSV Import & Field Mapping

For independent schools or non-Wonde tenants:

* Administrators upload standardised CSV rosters containing `forename`, `surname`, `email`, `year`, `form`, and `house`.
* The import processor matches records by unique school email, creating new accounts and updating existing student attributes without duplicating records.

***

## 2. Meeting Scheduling & Real-Time QR Check-In Workflow

```mermaid theme={null}
flowchart LR
    Leader["Club Leader / Coach"] -->|Displays on screen / print| QR["Session QR Code<br/>(Contains Meeting ULID)"]
    Student["Pupil Mobile / Tablet"] -->|Scans| QR
    QR --> Portal["/pupil/attend?ulid={ulid}"]
    Portal --> Livewire["Livewire Attendance Toggle"]
    Livewire -->|Instant State Change| Pivot["club_meeting_pupil Ledger"]
```

### Check-In Verification Rules

* **Same-Day Temporal Lock**: The self-attendance toggle is strictly enabled on the calendar day of the meeting (`Carbon::parse($meeting->date)->isCurrentDay()`).
* **Session Retraction**: If a student mistakenly marks attendance or leaves early, they can toggle the switch off on the same day.
* **Past & Future Protection**: For past meetings, a message directs the student to their club leader; for future sessions, the toggle remains locked until the scheduled date arrives.

***

## 3. Achievement Badges & Extracurricular Gamification

To foster student participation and celebrate extracurricular commitment, Cleverschool features an integrated recognition system:

> [accordion] Badge Visualisation
>
> Earned badges appear as vibrant, coloured icons in the pupil's profile header at `/pupil`. Unearned badges remain subtly dimmed, encouraging students to achieve upcoming milestones.

> [accordion] Hover Details & Tooltips
>
> Hovering over or tapping any badge displays the badge title and criteria description (e.g. *Century Club: Attended 100 extracurricular sessions* or *First Team Captain*).

> [accordion] Cross-Module Synergies
>
> Badges awarded in the **Clubs & Fixtures** module reflect immediately on the student's personal dashboard and within administrative summaries.

***

## 4. Pastoral Engagement Monitoring & Interventions

Extracurricular participation is a key indicator of student wellbeing and school belonging:

### Identifying Disengaged Cohorts

Pastoral leads, heads of year, and tutors can review the **Statistics Hub** (`/pupil/stats`) across flexible date ranges:

* **Cohort Disparities**: Compare Year 7 vs. Year 11 engagement to target key transition phases with new clubs.
* **House Competitions**: Track total attendance points accumulated per house to celebrate participation during termly house assemblies.
* **SEND & Vulnerable Pupil Overlap**: Cross-reference attendance records with the **Pupil Provisions** module to ensure students receiving targeted pastoral or learning support are actively involved in school life.

***

## 5. Troubleshooting & Support Scenarios

| Issue / Scenario | Root Cause | Recommended Action |
| :- | :- | :- |
| **Pupil cannot log in via SSO** | Email address in Google / Microsoft does not match the pupil's registered email in Cleverschool. | Verify email spelling in **Administration** > **Pupils** and update to match their institutional identity. |
| **Attendance switch is not visible** | The meeting date is in the past, in the future, or the student is using an invalid link. | Ensure the student is checking in on the exact day of the meeting. Staff can manually mark attendance via the club meeting register. |
| **Student marked as Not a Member** | The pupil has not been enrolled in the specific club roster. | The club leader can add the pupil to the club's member roster in **Clubs & Fixtures**. |
| **Student cannot reset password** | Account is linked to external SSO (Google / Microsoft). | Inform the student that authentication is managed by their school email provider. |
| **Staff need to verify student view** | Staff need to inspect a pupil's schedule or confirm attendance view. | Use the **Impersonate** action in `/admin/pupils` to inspect the live portal view. |

***

## Next Steps

> [card] [Tutorials](./tutorials)
>
> Review practical step-by-step guides for student check-in, statistics, and imports.

> [card] [Getting Started](./getting-started)
>
> Follow the initial setup and configuration guide for administrators.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.