Technical Induction Guide Β· External Engineering Review (IE & EU)

System Conception, Architecture & Ecosystem Navigation

Welcome to the technical evaluation portal for MentalHealthChange (MHC). This document is tailored specifically for external software engineers, architects, and technical reviewers. It outlines our software conception, our zero-bloat engineering philosophy, and the structured relationship between the 4 master specification documents governing the platform.

πŸ—ΊοΈ

Macroscopic Vision

Interactive topology in mindmap.html
βš™οΈ

Logic & Workflows

8 inter-role flows in functional_report
πŸ—„οΈ

Relational Persistence

32 MariaDB tables in db_report
πŸš€

Runtime & Portals

4 live environments in hub.html

The Architectural Conception of MentalHealthChange

MHC is neither a generic template nor a monolithic legacy system: it is a bespoke B2B Employee Assistance Program (EAP) and clinical wellbeing platform engineered specifically for the regulatory, privacy, and clinical governance requirements of Ireland and the European Union.

πŸ‘₯
Multi-Tenant & 4 Independent Portals

Strict 4-Role Boundary Segregation

The platform bridges four distinct stakeholders through decoupled interfaces, isolated sessions, separate authorization middleware, and distinct database access scopes:

  • βœ“ SuperAdmin Portal: Overall clinical governance, specialist document vetting, pre-approved email allowlists, and B2B bank settlement reconciliation.
  • βœ“ Company (HR Hub): Corporate employer suite for managing wellbeing credit tiers, sub-managers, departments, and viewing anonymized health insights.
  • βœ“ Provider Portal: Professional clinical workspace for licensed therapists (CORU/IACP certified), clinical intake assessment review, appointment slots, and two-step invoicing.
  • βœ“ Client Portal: Confidential patient-facing portal featuring guided intake, adaptive clinical scoring, specialist smart matching, and secure teleconsultation.
⚑
High-Performance & Zero Bloat

Lightweight, Audit-Ready Engineering

Rather than relying on fragile multi-gigabyte dependency trees or heavy full-stack frameworks prone to breaking upstream changes, MHC was conceived with an emphasis on transparency, predictable execution, and long-term maintainability:

  • βœ“ Vanilla PHP 8.2+ OOP: Modular, strictly-typed backend core utilizing PDO prepared statements and explicit parameter binding.
  • βœ“ Zero Framework Overhead: Eliminates build-step latency, fragile bundler pipelines, and supply-chain vulnerabilities common to massive npm packages.
  • βœ“ Vanilla JS & CSS Design Tokens: High-performance native browser components ensuring zero hydration lag and instantaneous initial page loads.
  • βœ“ Complete Audit Clarity: External engineers can inspect every single route, query, and transformation without having to unpack layers of opaque framework abstractions.
πŸ›‘οΈ
GDPR Compliance & Clinical Governance

Privacy-by-Design & Safeguarding

Handling sensitive mental healthcare data under EU and Irish jurisdiction requires clinical and statutory compliance to be baked into the relational schema from day one:

  • βœ“ k≥10 Anonymization Threshold: Corporate employers never have access to individual employee records; aggregate clinical insights are strictly masked until at least 10 active members participate.
  • βœ“ Real-Time Crisis / Red Alert Protocol: Question 9 of the PHQ-9 assessment (self-harm/suicidal ideation) immediately triggers safeguarding alerts and routes users to Irish emergency hotlines (Pieta House, Samaritans 116 123, 999/112).
  • βœ“ Defense-in-Depth Security: Bcrypt (Cost 12) password hashing, per-session CSRF tokens, and HttpOnly / SameSite session cookies.
  • βœ“ Direct B2B Bank Settlement: Automated 2-step clinician invoice submission reconciled via direct SEPA bank transfer in full alignment with Irish tax regulations.

The 4 Master Review Documents

To provide external software engineers with a comprehensive and frictionless audit experience, the platform is thoroughly documented across four specialized technical reports. Each covers a dedicated stratum of the system architecture.

🧭

Complementary Analysis Hierarchy

No single document stands alone: the Mindmap establishes the top-level conceptual topology; the Functional Report details end-to-end business rules and API endpoints; the DB Report exposes the relational schema underpinning all transactions; and the Hub provides a live cockpit to interact with the executing portals.

Doc #1 Β· Top-Level Overview Macroscopic Architecture
πŸ—ΊοΈ

Mindmap & Flowchart

mindmap.html

An interactive SVG visualizer charting the complete system topology, inter-service connections, cross-role workflows, and relational data flows in an animated graph view.

What the Reviewer Will Find Inside:
  • Dynamic graphical mapping of the 4 roles and 29 operational services.
  • Live SVG path tracing of the 8 end-to-end business workflows.
  • Interactive detail inspector panel revealing responsibilities per node.
  • Visual indicators linking operational services to the 32 database tables.
Doc #2 Β· Operational Logic Functional Specs & APIs
βš™οΈ

Functional Operations

functional_report.html

Comprehensive functional specification detailing role interactions, step-by-step transaction logic, data exchange contracts, and the catalogue of backend PHP JSON endpoints.

What the Reviewer Will Find Inside:
  • Step-by-step breakdown of the 8 core workflows (onboarding, matching, booking).
  • Catalog of 50+ REST/JSON API endpoints with HTTP methods and payloads.
  • 8 Annex Modules: Invoicing, Peer Chat, Crisis Alerts, Mail Queue, GDPR, etc.
  • State transition rules and role-permission matrices.
Doc #3 Β· Relational Schema Database Layer
πŸ—„οΈ

Database Architecture

db_report.html

Detailed technical specification of the MariaDB 10.4 / InnoDB database schema (sqls/Tablas_mhc_db.sql), detailing table definitions, constraints, indexes, and retention rules.

What the Reviewer Will Find Inside:
  • 32 normalized tables categorized into 6 functional modules.
  • 33 declared foreign keys with audit of ON DELETE / ON UPDATE cascading rules.
  • Real-time interactive table and column search engine with data type tags.
  • JSON schema specifications for clinical taxonomies and audit trails.
Doc #4 Β· Live Runtime Execution & UI Cockpit
πŸš€

Development Hub

hub.html

The central engineering cockpit linking directly to the runnable source code of all four operational portals, allowing engineers to test live screens, verify login flows, and review routes.

What the Reviewer Will Find Inside:
  • Direct launchpad to the 4 portals: Admin, Company, Provider, and Client.
  • Full screen inventory showing readiness status for all endpoints.
  • Live dev-environment status, deployment indicators, and stack trackers.
  • Direct routes for authentication testing, dashboards, and form workflows.

How These Documents Interconnect

To prevent information overload during code reviews, this matrix contrasts the analytical perspective, architectural layer, core question answered, and physical artifact associated with each document:

Document System Layer Core Question Answered Physical Artifact Mapped Direct Action
πŸ—ΊοΈ Mindmap
mindmap.html
System Topology "How do the 4 portals interact and what operational services comprise the entire ecosystem?" Services, actors, and overall system boundaries Explore β†—
βš™οΈ Functional Report
functional_report.html
Business Logic & APIs "What sequential logic governs cross-role workflows and what contract payloads do the PHP APIs expect?" 8 Workflows, 50+ APIs, and 8 Annex Modules Explore β†—
πŸ—„οΈ Database Report
db_report.html
Persistence & Schema "Where is each field stored, how are tables indexed, and what foreign keys guarantee referential integrity?" sqls/Tablas_mhc_db.sql (32 Tables) Explore β†—
πŸš€ Development Hub
hub.html
Live Runtime & UI "What do the actual dashboards look like, how do users authenticate, and where is the runnable code located?" Directories: admin/, company/, provider/, client/ Explore β†—

Recommended Review Roadmap for External Developers

Follow this 4-step sequence to achieve comprehensive technical understanding with optimal efficiency:

1

Conceptual Immersion

mindmap.html (~15 min)

Begin by exploring the interactive mindmap. Inspect the four quadrant roles, familiarize yourself with domain boundaries, and observe how operational services cluster logically.

1. Open Mindmap β†’
2

Functional Logic Review

functional_report.html (~25 min)

Analyze how actors interact across the 8 end-to-end workflows (corporate registration, PHQ-9 triage, therapist matching, session scheduling, and invoicing). Review the API catalogue.

2. Review Workflows β†’
3

Schema & Persistence Audit

db_report.html (~20 min)

Inspect the MariaDB entity-relationship model. Use the real-time search engine to evaluate primary keys, foreign key cascading constraints, JSON taxonomy structures, and GDPR retention policies.

3. Audit SQL Schema β†’
4

Live Runtime Verification

hub.html (~20 min)

Launch the Development Hub to interact with the executing portals. Test authentication screens, navigate specialist profiles, trigger assessments, and verify real frontend responses.

4. Test Live Portals β†’

Technology Stack & Architectural Patterns

The engineering foundation of MHC is built on principles of architectural simplicity, strict memory safety, and near-zero runtime latency.

🐘

Backend Architecture

Language PHP 8.2+ Modern OOP
Data Access Native PDO with Prepared Statements
Architecture Zero-Bloat / No Framework Bloat
Authentication Bcrypt (Cost 12) + HttpOnly Sessions
APIs JSON Endpoints with CSRF Protection
πŸ—„οΈ

Database Engine

RDBMS MariaDB 10.4+ / MySQL 8.0
Storage Engine InnoDB (ACID Compliant)
Charset / Collation utf8mb4_unicode_ci
Volume 32 Tables Β· 33 Foreign Keys
Flexible Columns Native JSON for Clinical Taxonomies
🎨

Frontend Engineering

Structure Semantic HTML5 (W3C Standards)
Styling Vanilla CSS Design System (Custom Tokens)
Client Logic Vanilla JS ES6+ (Fetch API, async/await)
Typography Outfit Β· Inter Β· JetBrains Mono
Dependencies Zero Bundlers / Zero npm Runtime Overhead
βš–οΈ

Compliance & Governance

Data Privacy GDPR Compliant (Ireland & EU)
B2B Anonymization Strict k≥10 Employee Masking
Clinical Scoring WHO-5, PHQ-2/9, GAD-2/7 Scales
Safeguarding Automated Q9 Red Alert Emergency Routing
Settlement Direct SEPA B2B Bank Transfer Model

Additional Ecosystem Resources

In addition to the 4 master documents, several specialized guides and schema scripts provide further context on clinical onboarding and database deployment:

Client Onboarding & Clinical Classification Guide

Illustrated step-by-step walkthrough of corporate verification, psychometric screening, and smart therapist matching.

client_onboarding_guide.html β†—

Ecosystem Master Cover Portal

Main public and administrative entrance showcasing product overview, marketing assets, and user guides.

indexx.html β†—

Raw MariaDB Schema DDL Script

Full SQL deployment script containing the 32 table creation statements, indexed lookups, and foreign key definitions.

Tablas_mhc_db.sql β†—