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

# Website Utilities

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

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

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

## Introduction

The Website Utilities module provides school leaders, administrators, and web developers with a centralised, secure bridge between Cleverschool and your public school website. It streamlines two critical operational challenges: facilitating spam-protected parent-to-staff communication with central administrative oversight, and managing automated, dynamic vocabulary content to enrich school website literacy.

***

### Conceptual Architecture & Data Model

The module structures website operations across two primary services—**Website Contacts** and **Website Words**—supported by public presentation layers and live JSON data endpoints:

```mermaid theme={null}
flowchart TD
    subgraph CoreEntities["Cleverschool Administration Engine"]
        AdminConfig["<b>School Administration Config</b><br/>• Central Office Email<br/>• Central Office Display Title"]
        ContactsRepo["<b>Website Contacts Directory</b><br/>• Staff Display Name & Email<br/>• Department / Group Category<br/>• Direct Email Toggle<br/>• Live User Account Sync (User / Archived / Non-User)"]
        WordsRepo["<b>Website Words Registry</b><br/>• Vocabulary Word & Meaning<br/>• Contextual Usage Example<br/>• Foreign / Community Language Translations (1 & 2)<br/>• Scheduled Activation Date (show_from)"]
    end

    subgraph Operations["Automated Background Services"]
        ReminderJob["<b>Weekly Stock Monitor</b><br/>• Scans future word reservoir<br/>• Dispatches low-word alerts when < 4 weeks remain<br/>• Validates active Website Manager assignments"]
        CacheManager["<b>Smart Cache Engine</b><br/>• Instant cache invalidation on edits<br/>• Automatic midnight cache rollover at activation date"]
    end

    subgraph PublicChannels["Public Web & Integration Channels"]
        PublicForm["<b>Interactive Contact Form</b> (<code>/contact</code>)<br/>• Turnstile & Honeypot Defence • Rate Limiting<br/>• Automated CC & Reply-To Office Routing"]
        JSONFeeds["<b>RESTful JSON Endpoints</b><br/>• <code>/website/contacts/list</code> & <code>/email</code><br/>• <code>/website/words/current</code> & <code>/previous</code><br/>• <code>/logo</code> (Public Logo Feed)"]
    end

    AdminConfig --> ContactsRepo
    ContactsRepo --> PublicForm
    ContactsRepo --> JSONFeeds
    WordsRepo --> ReminderJob
    WordsRepo --> CacheManager
    CacheManager --> JSONFeeds
```

***

## Roles & Permissions Matrix

Access to Website Utilities is managed through role-based permissions, segregating module configuration from day-to-day staff operations:

> [tab] Administrator
>
> **System Provisioning & Governance**
>
> * Enable or disable the Website Utilities module in **Administration** > **Modules**.
> * Assign the `Website Manager` role to designated administrative or IT personnel.
> * Receive automated `WebsiteManagerMissing` email alerts if the module is active without an assigned manager.
> * Possesses full administrative rights across contacts, vocabulary words, imports, and tenant configuration.

> [tab] Website Manager
>
> **Module Leadership & Configuration**
>
> * Configure global School Admin Email settings used for contact form `CC` and `Reply-To` routing.
> * Create, edit, reorder, and delete staff contacts and department groups.
> * Schedule, edit, and archive Word of the Week vocabulary entries.
> * Perform bulk spreadsheet imports and exports for contacts and words.
> * Receive automated weekly `WebsiteWordsReminder` alerts when vocabulary reserves run low.

> [tab] Website Owner
>
> **Operational Content Management**
>
> * View, edit, and maintain assigned website contact details.
> * Add, edit, and review upcoming Word of the Week schedules and translations.
> * Download contact and vocabulary data exports.

> [tab] Website Viewer
>
> **Read-Only Inspection**
>
> * Access and inspect the staff contact directory and status indicators.
> * View upcoming and historical Word of the Week vocabulary schedules without edit permissions.

***

## Core Operational Mechanics

### 1. Staff Contact Directory & Office Routing

The Contact management system (`/website/contacts`) provides a structured directory of staff members and departments available for website communication:

```mermaid theme={null}
flowchart TD
    Parent["Parent / Visitor on School Website"] -->|Visits <code>/contact</code>| Form["Public Staff Contact Portal"]
    Form -->|Submits Inquiry| Security["Security Layer<br/>• Cloudflare Turnstile Verification<br/>• Honeypot Validation<br/>• Rate Limit: 1 submission/minute"]
    Security -->|Validates| Notification["StaffContact Notification"]
    Notification -->|Direct Message| Staff["Staff Member Inbox<br/>(Named Teacher or Department)"]
    Notification -->|Carbon Copy (CC)| Office["School Admin Office Inbox<br/>(Central Record & Oversight)"]
    Staff -.->|Clicks Reply (Reply-To Header)| OfficeReply["Response Routed via School Office<br/>(Maintains Communication Quality)"]
```

* **Departmental Grouping**: Staff members are organised into custom groups (e.g. *Senior Leadership*, *Pastoral & Heads of Year*, *Subject Leads*, *Administrative Team*).
* **Drag-and-Drop Reordering**: Managers can reorder contacts within groups to control how names appear in dropdown menus and JSON feeds.
* **Live User Status Auditing**: Every contact email is dynamically evaluated against Cleverschool user records:
  * User (Green): Matches an active, verified staff account.
  * Not a user (Red): Email does not belong to any registered user in the tenant.
  * Archived user (Orange): Matches a former staff member whose account has been archived or soft-deleted.
  * Not a contact (Blue): Registered staff user who has not been published as a website contact.

***

### 2. Word of the Week Vocabulary Engine

The Word of the Week engine (`/website/words`) enables schools to cultivate ambitious literacy and multi-lingual awareness across their web footprint:

```mermaid theme={null}
flowchart LR
    Manager["Website Manager"] -->|Schedules Words| DB[("Vocabulary Registry")]
    DB -->|show_from arrives| LiveWord["<b>Active Word of the Week</b><br/>• Displayed via <code>/website/words/current</code>"]
    LiveWord -->|Next week's date arrives| Archive["<b>Word Archive</b><br/>• Available via <code>/website/words/previous</code>"]
    DB -->|Monitored by Tuesday Cron| Reminder["<b>Stock Health Check</b><br/>• > 9 future words: Green<br/>• 4–9 future words: Orange<br/>• 0–3 future words: Red & Email Alert"]
```

* **Chronological Activation (`show_from`)**: Each word is assigned an activation date (typically Mondays). The system automatically promotes the scheduled word to live status when its date arrives.
* **Intelligent Sequential Pre-population**: When adding a new word, the system automatically detects the latest scheduled date in the registry and pre-fills the form with the following consecutive week (`+7 days`).
* **Multi-Language Translations**: In addition to the English term, definition, and example sentence, each entry supports translations into two additional modern foreign or community languages (`Language 1` and `Language 2`).
* **Filtering & Archives**: Managers can toggle between viewing upcoming future words or including past historical words for review and editing.

***

## Developer Endpoints & JSON Feed Specifications

Cleverschool exposes high-performance, cached JSON endpoints for web developers to query directly from external Content Management Systems (WordPress, Webflow, Squarespace, Drupal, or custom JavaScript frontends):

> [accordion] 1. Public Staff Contacts List (/website/contacts/list)
>
> Returns a structured array of active staff contacts, sorted by departmental group and display order.
>
> **Endpoint**: `GET /website/contacts/list`\
> **Headers**: `Accept: application/json`
>
> ```json theme={null}
> [
>   {
>     "id": 1,
>     "name": "Mrs Sarah Jenkins",
>     "group": "Senior Leadership Team",
>     "email": "s.jenkins@cleverschool.test",
>     "email_direct": true,
>     "order": 1
>   },
>   {
>     "id": 2,
>     "name": "Mr David Hughes",
>     "group": "Pastoral & Heads of Year",
>     "email": "d.hughes@cleverschool.test",
>     "email_direct": true,
>     "order": 2
>   }
> ]
> ```

> [accordion] 2. School Administration Email Settings (/website/contacts/email)
>
> Returns the tenant's central school administrative email and official title for contact routing.
>
> **Endpoint**: `GET /website/contacts/email`\
> **Headers**: `Accept: application/json`
>
> ```json theme={null}
> {
>   "email": "admin@cleverschool.test",
>   "title": "St Clevers School Office"
> }
> ```

> [accordion] 3. Current Word of the Week (/website/words/current)
>
> Returns the currently active vocabulary word whose `show_from` date is active as of the current timestamp.
>
> **Endpoint**: `GET /website/words/current`\
> **Headers**: `Accept: application/json`
>
> ```json theme={null}
> {
>   "word": "Resilience",
>   "meaning": "The capacity to recover quickly from difficulties; toughness.",
>   "example": "Students demonstrated great resilience during exam preparations.",
>   "lang1": "Résilience (French)",
>   "lang2": "Resiliencia (Spanish)",
>   "show_from": "2026-11-02"
> }
> ```

> [accordion] 4. Historical Word Archive (/website/words/previous)
>
> Returns an array of all past vocabulary words in descending chronological order.
>
> **Endpoint**: `GET /website/words/previous`\
> **Headers**: `Accept: application/json`
>
> ```json theme={null}
> [
>   {
>     "word": "Perseverance",
>     "meaning": "Persistence in doing something despite difficulty or delay in achieving success.",
>     "example": "Her perseverance in mathematics led to outstanding progress.",
>     "lang1": "Persévérance (French)",
>     "lang2": "Perseverancia (Spanish)",
>     "show_from": "2026-10-26"
>   }
> ]
> ```

> [accordion] 5. Public School Logo Feed (/logo)
>
> Streams the school's official crest or logo as an authenticated binary image file directly from tenant storage.
>
> **Endpoint**: `GET /logo`\
> **Content-Type**: `image/png`, `image/jpeg`, or `image/svg+xml`

***

## Automated Notifications & Monitoring Lifecycle

The module incorporates automated background jobs to ensure continuous operational health:

> [accordion] Low Vocabulary Stock Reminder (WebsiteWordsReminder)
>
> Executed weekly every Tuesday at 11:55. If the total number of scheduled vocabulary words has no entries beyond one month ahead, an automated email notification is dispatched to all assigned `Website Managers` reminding them to replenish vocabulary entries.

> [accordion] Missing Website Manager Alert (WebsiteManagerMissing)
>
> Dispatched automatically to system `Administrators` if the Website module is enabled for the school tenant but no staff members have been assigned the `Website Manager` role.

> [accordion] Staff Contact Notification (StaffContact)
>
> Triggered immediately whenever a parent or visitor submits the public contact form (`/contact`). Dispatches a formatted email notification to the named staff member, automatically carbon-copying (`CC`) and setting the `Reply-To` address to the central School Administration Office.

***

## Next Steps & Practical Guides

> [card] [Getting Started Guide](./getting-started)
>
> Step-by-step setup walkthrough for administrators and newly appointed website managers.

> [card] [Tutorials & Workflows](./tutorials)
>
> Practical guides for contact routing, Excel bulk imports, and website widget integration.


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