MokoSuiteSupport/CLAUDE.md

MokoSuiteSupport

Multi-channel customer support for Joomla 6 — website chat, Facebook Messenger, WhatsApp, unified agent inbox, CSAT.

Quick Reference

Field	Value
Package	pkg_mokosuitesupport
Layer	Standalone (optional CRM integration)
Language	PHP 8.3+
Branch	develop on dev, merge to main (protected)
Wiki	MokoSuiteSupport Wiki

Architecture

Joomla package (pkg_mokosuitesupport) — standalone module, no MokoSuite dependencies required.

Optional Integrations

• MokoSuiteClient (Layer 0) — base platform features
• MokoSuiteCRM (Layer 1) — contact linking, ticket escalation
• Uses class_exists() checks to gracefully degrade when CRM not present

Channels

Website Chat · Facebook Messenger · WhatsApp Business · Instagram Direct (planned) · Email IMAP (planned)

Helpers (5)

• ConversationHelper — create, message, unified inbox, assign, close with CSAT
• AgentHelper — availability, auto-assign (least-busy), performance metrics
• CannedResponseHelper — quick replies, keyword search, categories
• WebhookChannelHelper — Facebook + WhatsApp inbound, conversation continuity
• CsatHelper — scoring, by-channel breakdown, weekly trend

Key Patterns

• Webhook handlers use FOR UPDATE transaction to prevent duplicate conversations on concurrent inbound
• Auto-assign picks agent with lowest active conversation count
• CSAT rating captured on conversation close (1-5 scale)

Source Directory

• source/pkg_mokosuitesupport.xml — package manifest
• source/packages/ — sub-extensions

Rules

• Never commit .claude/, .mcp.json, TODO.md, *.min.css/*.min.js
• Attribution: Authored-by: Moko Consulting
• Workflow directory: .mokogitea/
• Wiki: documentation lives in the Gitea wiki, not docs/ files
• Standards: MokoStandards
• Changelog: [Unreleased] only — release system assigns versions
• No mass email: use Mailchimp/external services for bulk sending

Coding Standards

• PHP 8.3+ / Joomla 6 patterns
• $this->getDatabase() in models, Factory::getContainer()->get(DatabaseInterface::class) in helpers
• Factory::getApplication()->getIdentity() for user
• FOR UPDATE inside transactions for race-condition-prone operations