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

# Clubs & Extracurricular Fixtures

> Workflows, Lifecycles & Integration

## End-to-End Extracurricular Lifecycle

The **Clubs & Fixtures** module unites activity scheduling, member enrolment, mobile QR check-in, register auditing, and student achievement badges into a continuous operational cycle.

```mermaid theme={null}
flowchart TD
    subgraph ProvisionPhase["Phase 1: Club Creation & Ownership"]
        P1["1. Administrator / Leader creates Club<br/><i>(Name, Day, Time, Location)</i>"]
        P2["2. Club Owner appointed<br/><i>(Assigned teacher / coach)</i>"]
        P1 --> P2
    end

    subgraph EnrolmentPhase["Phase 2: Pupil Enrolment & Rosters"]
        E1["3. Pupils enrolled into Club Roster<br/><i>(Live search & add via /clubs/club/id)</i>"]
        E2["4. Enrolment synchronised with Pupil Portal"]
        E1 --> E2
    end

    subgraph SchedulePhase["Phase 3: Meeting & Fixture Scheduling"]
        S1["5. Owner schedules Sessions / Fixtures<br/><i>(Date, Start/End Time, Opponent, Location)</i>"]
        S2["6. Session QR Code & Web Registers prepared"]
        S1 --> S2
    end

    subgraph AttendancePhase["Phase 4: Session Check-In & Verification"]
        A1["7. Meeting Commences"]
        A2["8a. QR Code Check-In via Pupil Portal (/pupil/attend)"]
        A3["8b. Staff Manual Register (/clubs/club/meeting/id)"]
        A4["9. Attendance recorded in database ledger (club_meeting_pupil)"]
        A1 --> A2 --> A4
        A1 --> A3 --> A4
    end

    subgraph AuditPhase["Phase 5: Meetings Oversight & Bulk Reminders"]
        M1["10. Manager audits Meetings Hub (/clubs/meetings)"]
        M2{"Registers Missing?"}
        M3["11. Bulk select meetings & trigger Remind"]
        M4["12. SendMeetingReminders Job dispatches emails to Owners"]
        M1 --> M2
        M2 -->|Yes| M3 --> M4
        M2 -->|No| G1
    end

    subgraph ImpactPhase["Phase 6: Recognition & Analytics"]
        G1["13. AwardBadges evaluates attendance thresholds"]
        G2["14. Badges displayed on Pupil Portal"]
        G3["15. Statistics Hub provides House, Year Group & Club analytics"]
        A4 --> G1 --> G2
        A4 --> G3
    end

    ProvisionPhase --> EnrolmentPhase
    EnrolmentPhase --> SchedulePhase
    SchedulePhase --> AttendancePhase
    AttendancePhase --> AuditPhase
```

***

## 1. Club Creation & Member Roster Management

Establishing extracurricular activities with designated staff leadership and stable student rosters:

* **Ownership Delegation**: Appointed `Club Owners` have full management control over their assigned activities, relieving central administrative burden.
* **Flexible Membership**: Pupils can be enrolled into fixed club rosters (e.g. *Chamber Choir*, *U15 Rugby Squad*) for fast register taking, while casual drop-in clubs (e.g. *Homework Club*, *Board Games Club*) can register any attendee on the day using **Other Attendance**.

***

## 2. Meeting Scheduling & Sports Fixtures

Accommodating both regular weekly clubs and inter-school competitive sports matches:

* **Session Timing**: Standard start and end times ensure accurate scheduling visible across both staff and student portals.
* **Competitive Fixture Records**: Capture opponent school names, home or away venue status, and post-match scorelines for league standings and school newsletters.
* **Direct Breadcrumb Navigation**: The main club list includes direct navigation buttons to jump straight to the central meetings list.

***

## 3. Real-Time QR Code Check-In Architecture

```mermaid theme={null}
flowchart LR
    Leader["Club Leader / Coach"] -->|Projects / Prints| QR["Session QR Code<br/>(Contains Meeting ULID)"]
    Student["Pupil Mobile / Tablet"] -->|Scans| QR
    QR --> Portal["Pupil Portal (/pupil/attend?ulid=...)"]
    Portal --> Livewire["Attendance Toggle Switch"]
    Livewire -->|Instant Toggle| Ledger["club_meeting_pupil Ledger"]
    Ledger --> Today["Pupils Today Monitor (/clubs/pupils/today)"]
```

### Check-In Safeguards

* **Same-Day Temporal Lock**: Pupils can only mark themselves as present on the calendar day of the meeting (`isCurrentDay()`).
* **Instant Safeguarding Visibility**: As soon as a pupil scans or a teacher checks a box, the student appears in `/clubs/pupils/today` for duty staff and bus coordinators.

***

## 4. Central Meetings Hub & Automated Reminder Workflow

The **Meetings Hub** (`/clubs/meetings`) provides coordinators with school-wide oversight of extracurricular register completion:

```mermaid theme={null}
flowchart TD
    Coordinator["Coordinator / Manager"] -->|Opens| Hub["Meetings Directory (/clubs/meetings)"]
    Hub --> Filter["Filter Date Range (Default: Last 7 Days, max=today)"]
    Filter --> Search["Search Club Name or Owner Name"]
    Search --> Selection["Select Rows / Select Page / Select All"]
    Selection --> Modal["Confirmation Modal (clubs::clubs.meetings.remind)"]
    Modal --> Job["Dispatch SendMeetingReminders Job"]
    Job --> Email["Automated Email sent to Meeting Owners without attendance"]
```

### Bulk Reminder Features

* **Zero-Attendance Filtering**: The `remindSelected` action automatically queries `$selectedRowsQuery->doesntHave('pupils')`, ensuring reminder emails are only dispatched for meetings that genuinely lack recorded attendance.
* **Select All Records**: Supports selecting individual rows, all visible rows on a page, or all matching records across paginated datasets.
* **Date Restrictions**: The date range picker is capped at `max="today"`, ensuring past sessions are audited without selecting future dates.
* **Automated Daily Schedule**: In addition to on-demand manual bulk reminders, a scheduled task (`SendClubsReminders`) runs automatically every morning at 09:00, checking for any club meetings from the previous day (`yesterday`) that have no recorded attendance and notifying the respective club owners.

***

## 5. Club Attendance Statistics

The **Statistics Hub** (`/clubs/statistics`) provides attendance charts for houses, forms, year groups, and clubs over a selected date range. Open the club chart for a detailed table, then select a column heading to sort the clubs by name, total attendance, meeting count, or average attendance per meeting.

The club table counts scheduled meetings in the selected range, including meetings without recorded attendance. Average attendance is the total number of pupil attendance records divided by the meeting count and is displayed to one decimal place; a club with no meetings in the range has an average of `0.0`.

***

## 6. Achievement Badges & Recognition Pipeline

To encourage sustained extracurricular participation, Cleverschool features an automated gamification pipeline:

> [accordion] AwardBadges Automated Job
>
> The `AwardBadges` job runs in the background to evaluate cumulative pupil attendance records against predefined criteria:
>
> * **First Timer**: Awarded upon attending the first extracurricular club session.
> * **Regular Attender**: Awarded after reaching sustained attendance milestones in a single club.
> * **Club Explorer & Super Explorer**: Awarded to pupils who participate across multiple distinct club categories.
> * **Team Player & Team Winner**: Awarded for participating in and winning competitive sports fixtures.

> [accordion] Student Showcase
>
> Badges appear prominently on the student's profile header in the **Pupil Portal** (`/pupil`), driving healthy competition and engagement.

***

## 7. Safeguarding & Duty Monitoring (`/clubs/pupils/today`)

Duty managers, receptionists, and late-bus coordinators rely on real-time attendance registers:

* **Late Bus Verification**: Cross-reference student pickup lists with pupils checked into after-school clubs.
* **Emergency Evacuations**: Immediate visibility into which students are on site attending clubs outside normal school timetable hours.

***

## 8. Troubleshooting & Common Operational Scenarios

| Issue / Scenario | Root Cause | Recommended Action |
| :- | :- | :- |
| **Pupil cannot check in via QR code** | The meeting date is not today, or the student is not logged in. | Verify the meeting date. Ensure student is authenticated on the Pupil Portal. Staff can manually mark attendance. |
| **Pupil not listed on club register** | Student has not been added to the club's member roster. | Search for the pupil under **Other Attendance** for immediate check-in, and add them to **Club Members** for future sessions. |
| **Reminders not sent for some selected rows** | The meeting already has recorded pupil attendance. | The bulk reminder workflow deliberately filters out meetings with existing attendees to avoid spamming compliant staff. |
| **Cannot select future dates in date picker** | The Meetings date picker is constrained to `max="today"`. | By design, attendance audits only apply to past and current sessions. |
| **Club not visible in My Clubs** | The authenticated user is not set as the `Club Owner`. | Toggle the filter to **All Clubs** or request a `Clubs Manager` to reassign ownership. |

***

## Next Steps

> [card] [Tutorials](./tutorials)
>
> Review practical step-by-step guides for QR check-in, bulk reminders, and taking registers.

> [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.