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

# 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 updates House & Year Group charts"]
        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. 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.

***

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

***

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