MokoSuiteCross/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

MokoSuiteCross -- Cross-posting Joomla content to social media, email marketing, and chat platforms

Field	Value
Platform	joomla
Language	PHP
Default branch	main
License	GPL-3.0-or-later
Wiki	MokoSuiteCross Wiki
Standards	MokoStandards

Common Commands

make build        # Build the project
make lint         # Run linters
make validate     # Validate structure
make release      # Full release pipeline
make minify       # Minify CSS/JS assets
make clean        # Clean build artifacts

composer install  # Install PHP dependencies

Architecture

This is a Joomla package extension (pkg_mokosuitecross) containing sub-extensions:

com_mokosuitecross (Component)

• Admin backend for managing services, post queue, templates, and logs
• Joomla 5/6 MVC: Dashboard, Services, Posts, Logs (list/edit each)
• Namespace: Joomla\Component\MokoSuiteCross\Administrator
• Database tables: #__mokosuitecross_services, #__mokosuitecross_posts, #__mokosuitecross_templates, #__mokosuitecross_logs

plg_system_mokosuitecross (System Plugin)

• Hooks onContentAfterSave to trigger cross-posting when articles are published
• Dispatches to registered service plugins via the mokosuitecross plugin group
• Namespace: Joomla\Plugin\System\MokoSuiteCross

plg_content_mokosuitecross (Content Plugin)

• Hooks onContentBeforeDisplay to add cross-post status badges to articles
• Namespace: Joomla\Plugin\Content\MokoSuiteCross

plg_webservices_mokosuitecross (WebServices Plugin)

• REST API endpoints for posts and services
• Namespace: Joomla\Plugin\WebServices\MokoSuiteCross

Service Plugins (mokosuitecross group)

Each platform is a separate plugin in the custom mokosuitecross plugin group:

• plg_mokosuitecross_facebook — Facebook/Meta Graph API
• plg_mokosuitecross_twitter — X/Twitter API v2
• plg_mokosuitecross_linkedin — LinkedIn Share API
• plg_mokosuitecross_mastodon — Mastodon API
• plg_mokosuitecross_bluesky — Bluesky AT Protocol
• plg_mokosuitecross_mailchimp — Mailchimp Campaigns API
• plg_mokosuitecross_telegram — Telegram Bot API (default @mokosuite_bot + custom bot)
• plg_mokosuitecross_discord — Discord Webhooks
• plg_mokosuitecross_slack — Slack Incoming Webhooks

Database Schema

Four tables:

#__mokosuitecross_services:

• id, title, alias, service_type (facebook, twitter, etc.)
• credentials (JSON encrypted), params (JSON)
• published, ordering, created, modified, created_by

#__mokosuitecross_posts:

• id, article_id (FK to #__content), service_id (FK)
• status (queued/posting/posted/failed/scheduled)
• message, platform_post_id, platform_response (JSON)
• scheduled_at, posted_at, retry_count
• created, modified

#__mokosuitecross_templates:

• id, service_type, title, template_body
• published, ordering, created, modified

#__mokosuitecross_logs:

• id, post_id (FK), service_id (FK)
• level (info/warning/error), message, context (JSON)
• created

Rules

• Never commit .claude/, .mcp.json, TODO.md, or *.min.css/*.min.js
• Never commit API keys, tokens, or credentials — these go in Joomla's encrypted params
• Attribution: use Authored-by: Moko Consulting in commits
• Branch strategy: develop on dev, merge to main for release
• Minification: handled at build time (CI)
• Wiki: documentation lives in the Gitea wiki, not in docs/ files
• Standards: this repo follows MokoStandards

Coding Standards

• PHP 8.1+ minimum
• Joomla 5/6 DI container pattern: services/provider.php → Extension class
• Legacy stub .php file required for plugin loader but empty
• SubscriberInterface for event subscription (not on* method naming)
• bind() → check() → store() for Table operations (not save())
• Language file placement: site (no folder) vs admin (folder="administrator")
• SPDX license headers on all PHP files
• Service plugins MUST implement MokoSuiteCrossServiceInterface