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

> Conceptual Model, Roles & Operations

> [card] [Getting Started](./getting-started)

> [card] [Tutorials](./tutorials)

> [card] [Workflows](./workflows)

## Introduction

The **Pupil Portal** (Pupil Area) module provides schools with a dedicated, secure pupil-facing subsystem that connects students directly to their extracurricular schedule, sports fixtures, attendance records, and house achievements. Operating in tandem with the school's **Clubs & Fixtures** and **Admin** modules, the portal encourages student responsibility and autonomy through self-service meeting check-in, transparent fixture tracking, and engaging statistical dashboards.

***

## Conceptual Architecture Model

The Pupil Portal structure brings together core pupil demographics, authentication guards, club meetings, attendance records, and engagement analytics:

* **Pupil Entity (`Pupil`)**: The central student record storing core demographic attributes (forename, surname, email, year group, form, house, and profile avatar). Managed centrally via MIS synchronisation (Wonde) or administrative import.
* **Pupil Authentication Guard (`auth:pupil`)**: An isolated authentication domain specifically for student accounts, supporting email verification (`verified.pupil`), password resets, OAuth SSO (Google / Microsoft Azure AD), and secure staff impersonation tokens (`/pupil/impersonate/{token}`).
* **Club Meetings & Fixtures (`ClubMeeting`)**: Scheduled extracurricular sessions and competitive sports matches associated with specific clubs, featuring start dates, times, home/away status, opponent names, and match results.
* **Attendance Ledger (`club_meeting_pupil`)**: The pivot association recording pupil attendance at club meetings, validated through teacher registers or direct pupil QR check-in on the day of the meeting.
* **Achievement Badges (`Badge` & `pupil_badges`)**: Extracurricular milestone recognitions and badges linked to pupils and proudly showcased in their profile header.
* **Engagement & House Analytics (`Statistics`)**: Dynamic calculation engines aggregating attendance figures across houses, forms, and year groups over selectable date ranges.

```mermaid theme={null}
flowchart TD
    subgraph DataIngestion["Pupil Identity & Data Layer"]
        MIS["<b>School MIS / Wonde</b><br/>Automated roster sync"]
        AdminRoster["<b>Admin Pupil Directory</b><br/>CSV import & manual roster management"]
        MIS --> Pupil["<b>Pupil Record (Pupil)</b><br/>Name • Form • Year • House • Avatar<br/><i>Unique Student Identifier</i>"]
        AdminRoster --> Pupil
    end

    subgraph AuthLayer["Pupil Authentication Guard (auth.pupil)"]
        SSO["<b>Single Sign-On (OAuth)</b><br/>Google Workspace / Microsoft 365"]
        EmailAuth["<b>Email & Password</b><br/>Self-service reset & verification"]
        Impersonate["<b>Staff Impersonation</b><br/>One-time secure pastoral token"]
        SSO --> AuthSession["<b>Active Pupil Session</b><br/>Isolated pupil guard"]
        EmailAuth --> AuthSession
        Impersonate --> AuthSession
        Pupil --> AuthSession
    end

    subgraph PortalFeatures["Pupil Portal Dashboard (/pupil)"]
        MeetingsList["<b>Club Meetings & Fixtures</b><br/>Upcoming sessions • Match scores • Sort & search"]
        Badges["<b>Achievement Badges</b><br/>Extracurricular recognition milestones"]
        QRCheckIn["<b>Meeting Attendance (/pupil/attend)</b><br/>Same-day QR self-registration"]
        StatsEngine["<b>School Analytics (/pupil/stats)</b><br/>House & Year group engagement charts"]

        AuthSession --> MeetingsList
        AuthSession --> Badges
        AuthSession --> QRCheckIn
        AuthSession --> StatsEngine
    end

    subgraph ClubsIntegration["Clubs & Fixtures Integration"]
        ClubMeeting["<b>Club Meeting (ClubMeeting)</b><br/>Date • Time • Opponent • Location"]
        Attendance["<b>Attendance Pivot</b><br/>Live check-in recorded"]

        ClubMeeting --> MeetingsList
        QRCheckIn -->|Updates| Attendance
        Attendance -->|Feeds| StatsEngine
    end
```

***

## Authentication & Security Architecture

The Pupil Portal is built on a dedicated, isolated authentication guard (`auth:pupil`) to ensure strict separation between staff administrative privileges and student access:

* **Single Sign-On (SSO)**: Students can sign in using their existing school Google Workspace or Microsoft 365 credentials via `/pupil/login/{provider}`.
* **Email Verification (`PupilEmailIsVerified`)**: Ensures pupil email addresses are verified prior to granting full portal access.
* **Password Reset Workflows**: Integrated email reset tokens allowing pupils to reset passwords securely (when not using external identity providers).
* **Pastoral Impersonation Engine**: Authorised staff with administrative access can generate secure, short-lived impersonation tokens via `tenancy()->impersonate(...)`, redirecting directly to `/pupil/impersonate/{token}` to inspect the exact view presented to a specific student without needing their password.

***

## Roles & Permissions Matrix

The module operates across staff management roles and the dedicated pupil end-user role:

| Permission / Action | Administrator | Pupil Manager (`pupils_manager`) | Pupil Owner (`pupils_owner`) | Pupil Viewer (`pupils_viewer`) | Pupil (`auth:pupil`) |
| :- | :-: | :-: | :-: | :-: | :-: |
| **Enable / Disable Pupil Portal** | | | | | |
| **Assign Pupil Managers** | | | | | |
| **Manage Owners & Viewers** | | | | | |
| **Import & Manage Pupil Roster** | | | | | |
| **Trigger Wonde MIS Sync** | | | | | |
| **Impersonate Pupil Accounts** | | | | | |
| **Archive & Restore Pupils** | | | | | |
| **View Pupil Extracurricular Dashboard** | | | | |  *(Own)* |
| **Mark Attendance via QR / Toggle** | | | | |  *(Same-day)* |
| **Inspect House & Year Attendance Analytics** | | | | | |

***

## Core Screen Tour

### 1. Pupil Dashboard (`/pupil`)

The main student landing page displaying a comprehensive overview of extracurricular commitments:

* **Pupil Profile Header**: Shows the student's name, school logo, profile avatar, and an interactive showcase of earned achievement badges.
* **Meetings & Fixtures Table**: Filterable, sortable list of all club meetings and sports matches the pupil is scheduled to attend.
* **Match Score Indicators**: For competitive fixtures, displays final scores with colour coding (**Green** for victory, **Red** for defeat, **Yellow** for draw).
* **Quick Search & Sorting**: Instant keyword filtering by club name or fixture opponent, with column sorting by date or club.

### 2. Meeting Attendance Check-In (`/pupil/attend?ulid={ulid}`)

The mobile-optimised check-in interface accessed via meeting QR codes or direct session links:

* **Meeting Header**: Confirms the club name, meeting date, start time, home/away status, and opponent.
* **Same-Day Attendance Switch**: An instant Livewire toggle allowing pupils to mark themselves as attending on the day of the meeting.
* **Status Feedback**: Clear contextual banners explaining whether a meeting is in the future, has already taken place, or if the student is not yet a registered club member.

### 3. Extracurricular Analytics Hub (`/pupil/stats`)

A dynamic school-wide statistics dashboard comparing participation across cohorts:

* **Interactive Date Range Filter**: Quick presets (*Yesterday*, *This Week*, *Last Week*, *Last 7 Days*, *This Month*, *Last Month*, *Year to Date*) or custom date intervals.
* **Year Group Charts**: Compares total pupil attendances across year groups to evaluate cohort engagement.
* **House Competition Charts**: Visualises total attendance points per house, supporting school house cup competitions and pastoral reward schemes.

### 4. Pupil Administration Console (`/admin/pupils`)

The central staff management hub for pupil accounts and directory maintenance:

* **Pupil Search & Filtering**: Multi-field querying across forename, surname, year group, form, house, and email address.
* **Bulk CSV Import**: Standardised spreadsheet upload facility to create or update entire year groups with intelligent heading mapping.
* **Pupil Actions Menu**: One-click staff actions to edit pupil details, dispatch password reset notifications, archive departing students, or launch secure pupil impersonation sessions.

***

## Next Steps

> [card] [Getting Started Guide](./getting-started)
>
> Step-by-step setup instructions for administrators and newly appointed Pupil Managers.

> [card] [Tutorials & Walkthroughs](./tutorials)
>
> Practical walkthroughs for QR attendance check-in, statistical analysis, and roster management.


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