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

# Complaints Management

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

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

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

## Introduction

The Complaints Management module equips schools with a structured, step-by-step framework to process, investigate, and record complaints objectively and transparently.

### Conceptual Architecture

The module structures complaint data into cohesive case dossiers that maintain a complete history from initial recording to final resolution:

* **Case Dossier**: Each complaint has a unique reference number (e.g. `CMP-2026-001`), tracking complainant contact details, formal statements, internal school notes, AI evaluations, timeline milestones, and outcome determinations.
* **Stage Progression State Machine**: Cases move through structured states—from *Opened* and *Submitted* to *Stage 2 Triaged*, formal outcome resolution (*Upheld*, *Partially Upheld*, *Not Upheld*), and optional escalation to *Stage 3 Open*, *Stage 3 Requested*, and *Stage 3 Triaged*.
* **External Complainant Portal**: Complainants interact via a dedicated, secure portal at `/complaint`. They receive passwordless magic-link authentication and one-time password (OTP) verification, ensuring data privacy and ease of access on any device.
* **Internal Investigation Notes**: School staff capture contextual background notes alongside each element of the complaint without exposing internal commentary to the complainant.
* **AI Policy Cross-Referencing**: Built-in AI agents consult the school's published complaints procedure via web search to ensure all assessments strictly reflect school-specific deadlines, escalation limits, and definitions.

***

## Roles & Permissions Matrix

The module uses granular role-based access control to enforce segregation of duties between leadership oversight, case investigation, and audit observation:

> [tab] Administrator
>
> **System & Module Configuration**
>
> * Enable and disable the Complaints module in tenant administration.
> * Assign the `Complaints Manager` role to senior leaders or complaints coordinators.
> * Receive system-level alerts if the module is enabled without an assigned manager.

> [tab] Complaints Manager
>
> **Full Module Leadership & Decision-Making**
>
> * Create new complaint records and dispatch initial login links to complainants.
> * Assign and reassign case ownership to designated investigating officers (`Complaints Owner`).
> * Initiate AI triage and make formal triage decisions (*Investigate*, *Informal*, *Out of scope*, *Unreasonable*).
> * Review, edit, and dispatch formal response communications to complainants.
> * Determine and record formal Stage 2 and Stage 3 investigation and review outcomes (*Upheld*, *Partially Upheld*, *Not Upheld*).
> * Authorise escalation to Stage 3 panel reviews and record formal panel outcomes.
> * Impersonate complainants to assist with technical queries or verify portal views.
> * Archive, restore, or delete inactive records.
> * Configure module settings, including departmental sender details and published procedure URLs.

> [tab] Complaints Owner
>
> **Case Investigation & Evidence Gathering**
>
> * Access and review assigned complaint dossiers.
> * Enter internal investigation notes across all complaint dimensions (details, Stage 1 actions, unsatisfactory reasons, requested remedies).
> * Trigger AI triage assessments for assigned complaints.
> * Formulate investigation findings and recommend outcomes to the Complaints Manager.

> [tab] Complaints Viewer
>
> **Read-Only Oversight & Governance**
>
> * View active and archived complaint dossiers and status indicators.
> * Export and print official PDF complaint dossiers for governor meetings and audit reviews.
> * Cannot create, edit, reassign, or change the status of any complaint record.

***

## User Interface & Screen Tour

### 1. Complaints Management Dashboard

Accessible via the main sidebar navigation, the dashboard presents a searchable, filterable table of all school complaints:

* **Active vs. Archived Views**: Toggle between active complaints and archived records using the top bar control.
* **Live Search**: Rapidly find complaints by complainant name, email address, or reference number.
* **Progression Stage Filter**: Filter records by current state:
  * *All complaints*: Complete list of active records.
  * *Opened*: Record created; awaiting complainant submission via the external portal.
  * *Submitted*: Formally submitted by the complainant; awaiting triage or owner assignment.
  * *Upheld* / *Partially Upheld* / *Not Upheld*: Investigation concluded with a confirmed outcome.
  * *Stage 3 Open*: Escalated; awaiting complainant Stage 3 submission.
  * *Stage 3 Requested*: Complainant appeal submitted; awaiting Stage 3 triage.
  * *Stage 3 Triaged*: Stage 3 triage completed; ready for panel decision or rejection response.
* **Row Menu Actions**: Quickly view dossiers, edit complainant details, assign owners, start Stage 3 reviews, impersonate complainants, or export PDF summaries.

### 2. The Complaint Dossier View

Clicking any complaint opens the detailed case dossier, featuring structured tabs:

* **Triage Tab**: Compare the complainant's submission alongside the school's internal investigation notes. Trigger AI triage to evaluate scope, reasonableness, and informal resolution potential.
* **Investigation & Outcome Tab**: Once formal investigation is selected, review the AI investigator briefing, document findings, and record formal outcomes (*Upheld*, *Partially Upheld*, *Not Upheld*) with mandatory outcome justifications.
* **Response Tab**: When a complaint is handled informally, rejected as out of scope, or determined unreasonable, review the AI-drafted formal response letter, edit the text, and send it directly to the complainant with one click.
* **Stage 3 Tabs & Outcome**: When a Stage 3 review is initiated, access dedicated tabs for Stage 3 notes, AI Stage 3 triage, panel decisions, formal response generation, and the **Stage 3 Review Outcome** card with its dedicated **Stage 3 Outcome Reason** tab for recording and publishing panel determinations.

### 3. Complainant External Portal (`/complaint`)

Parents and complainants access a streamlined, dedicated portal:

* Secure login via email and one-time verification code (OTP).
* Clear prompts to provide full details of the concern, previous informal actions taken, reasons for dissatisfaction, and desired resolution.
* Automatic form locking upon submission to guarantee evidential integrity.
* Live status confirmation and access to official school responses, investigation outcomes, and Stage 3 review determinations.

***

## Next Steps & Guides

> [card] [Tutorials & Practical Guides](./tutorials)
>
> Step-by-step walkthroughs for logging complaints, conducting AI triage, and managing panel outcomes.

> [card] [End-to-End Workflows](./workflows)
>
> Explore step-by-step lifecycles for Stage 2 investigations, AI triage, and Stage 3 appeals.


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