MentalHealthChange — Technical-Functional Operations Report

👥 Operational Functions by User Role

MentalHealthChange operates across 4 core user roles with Role-Based Access Control (RBAC) and privacy isolation. Below is the operational specification per actor:

Administrator / Clinical Lead ROLE_ADMIN

Global User Management

api/admin/admin_users.php

Full CRUD operations for clients, specialists, corporate HR reps, and administrative staff. Account status toggling (`is_active`).

SubRole & Permission Matrix

api/admin/subroles.php

Creation of fine-grained subroles (e.g. Clinical Lead) and assignment of qualified permissions (`PERM_ADMIN_CL_MESSAGES_READ`).

Corporate Invitation Generation

api/admin/company-invitation-create.php

Issuance of 32-character bulk registration security tokens for corporate client employees.

Crisis Alert Triage & Resolution

api/alerts/resolve.php

Real-time monitoring of critical risk alerts and logging resolution audit trails (`resolved_by`, `notes`).

Knowledge Base (FAQ) Management

api/admin/faq-manage.php

Creation, editing, and ordering of role-segmented help desk articles.

Employer (Company HR) ROLE_COMPANY

Workforce Wellbeing Dashboard

api/company/home.php

Consolidated overview of enrolled members, total session consumption, and active benefit budgets.

Aggregated Anonymous GDPR Reports

api/company/reports.php

Impact statistics with privacy protection threshold (≥ 10 active members to prevent individual tracking).

Billing & Corporate Allowances

api/company/billing.php

Statement history for `company_id` and employee quota management (`sessions_per_member`).

Direct Support Channel

api/company/contact.php

Direct dispatch of contract adjustment and quota expansion requests to administration.

Specialist (Provider / Coach) ROLE_PROVIDER

Agenda & Availability Settings

api/provider/availability-save.php

Definition of weekly working slots (`start_time`, `end_time`, `buffer_time`) and timezone settings.

Session Execution & 5-Metric Rating

api/provider/session-complete.php

Appointment completion with confidential progress notes and 5-dimension outcome rating.

Crisis Safety Care Plans

api/provider/safety-plan-save.php

Formulation of emergency contingency plans featuring coping strategies and medical contacts.

Clinical Assessment Supervision

api/provider/questionnaires.php

Review of PHQ-9, GAD-7, and WHO-5 scores for assigned client rosters.

Fee Invoice Submissions

api/provider/invoice-submit.php

Submission of completed session payout requests for direct bank settlement by administration.

Member (Client) ROLE_CLIENT

Self-Registration via Corporate Token

api/client/register.php

Account creation automatically bound to issuing employer invitation token.

Intake & Interest Focus

api/client/questionnaire-save-intake.php

Registration of initial assessment and wellness priorities (`client_interests`).

Appointment Rescheduling (24h Policy)

api/client/session-request-change.php

Rescheduling or cancellation requests calculating > 24h or < 24h notice.

Mental Health Psychometrics & Triage

api/client/questionnaire-save.php

Completion of PHQ-9/GAD-7 psychometric scales and 3-minute risk screening.

Encrypted Specialist Chat

api/messages.php

Bidirectional private messaging with assigned mental health specialist.

🧾 Annex A: Invoicing & Financial Settlement Module

Detailed specification of fee submissions, invoice states, and B2B settlement between specialists, MHC administration, and corporate accounts.

Invoice Status	Stage Description	Responsible Actor	Backend Action / API
pending	Draft invoice generated automatically upon appointment completion in `appointments`.	System / Provider	`Appointment::completeSession()` creates record in `invoices`.
submitted	Specialist submits statement for administrative review and fee payout approval.	Specialist (Provider)	`POST /api/provider/invoice-submit.php`
paid	Payment cleared via direct Bank Transfer. Transaction reference recorded in `payments`.	Administrator / Finance	`Invoice::markAsPaid()` and insert into `payments`.

💡 Financial Relationship Model

• Each invoice in invoices binds optionally to a specific appointment (session_id), specialist (provider_id), member (client_id), and corporate account (company_id).
• If a member or employer account is deactivated, Foreign Key constraints enforce ON DELETE SET NULL, preserving legal accounting records for tax audit compliance in Ireland & EU.

❓ Annex B: Knowledge Base & Help Desk Module (FAQs)

Self-service knowledge base resolving operational and clinical queries per persona.

Target Role (`target_role`)	Typical FAQ Content	Public Endpoint	Access Level
all	General platform overview, GDPR standards, and security encryption.	`GET /api/faq/list.php?role=all`	Public / All Users
client	Booking consultations, 24h cancellation rules, employer privacy guarantees.	`GET /api/faq/list.php?role=client`	Members / Clients
provider	Clinical note guidelines, 5-metric ratings, Zoom/Meet setup, fee payouts.	`GET /api/faq/list.php?role=provider`	Specialists / Providers
company	Interpreting aggregated WHO-5 metrics, quota management, B2B billing.	`GET /api/faq/list.php?role=company`	Corporate HR Reps
admin	Crisis escalation procedures, user governance, subrole creation.	`GET /api/faq/list.php?role=admin`	Admins Only

🛠️ FAQ Catalog Administration

Administrators manage articles via api/admin/faq-manage.php, categorizing entries (`category_id`), defining search tags (`keywords`), and configuring display ordering (`display_order`).

🚨 Annex D: Crisis Alert Protocol & Clinical Risk Triage

Automated safeguarding mechanism detecting self-harm risk or severe depression indicators.

Alert Trigger Source	Trigger Criteria	Generated Severity	Response Action
`crisis_assessments`	Member answers safety screening questions affirmatively for self-harm risk.	critical	Immediate dashboard alert and high-priority email queued to Clinical Lead.
PHQ-9 / GAD-7 Psychometrics	Psychometric score reaches "Severe" range (> 20 pts).	warning	Notification dispatched to specialist to adjust care plan.
Appointment Attendance	Member accumulates consecutive unexcused absences.	info	Preventive notification sent to support team.

📋 Safety Care Plans (`safety_care_plans`)

In elevated risk situations, specialists formulate contingency plans detailing coping strategies, emergency contacts, and safe environment guidelines. Plans require explicit confirmation (is_confirmed=1) by the member.

Technical-Functional Operations & Inter-Role Report

👥 Operational Functions by User Role

🔄 End-to-End Cross-Role Workflows

🧾 Annex A: Invoicing & Financial Settlement Module

💡 Financial Relationship Model

❓ Annex B: Knowledge Base & Help Desk Module (FAQs)

🛠️ FAQ Catalog Administration

💬 Annex C: Encrypted Peer-to-Peer Messaging & Audit Mode

🔒 Dual Soft-Delete Privacy

👁️ Clinical Lead Supervision (Read-Only Mode)

🚨 Annex D: Crisis Alert Protocol & Clinical Risk Triage

📋 Safety Care Plans (`safety_care_plans`)

📧 Annex E & F: Email Queue, RBAC System & GDPR Compliance

📨 Asynchronous Email Queue

🔐 Granular RBAC & SubRoles

🛡️ GDPR Consent & Legal Audit Logs