MokoSuiteCross/CLAUDE.md

CLAUDE.md

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

Project Overview

MokoJoomCross -- 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	MokoJoomCross 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_mokojoomcross) containing sub-extensions:

com_mokojoomcross (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\MokoJoomCross\Administrator
• Database tables: #__mokojoomcross_services, #__mokojoomcross_posts, #__mokojoomcross_templates, #__mokojoomcross_logs

plg_system_mokojoomcross (System Plugin)

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

plg_content_mokojoomcross (Content Plugin)

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

plg_webservices_mokojoomcross (WebServices Plugin)

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

Service Plugins (mokojoomcross group)

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

• plg_mokojoomcross_facebook — Facebook/Meta Graph API
• plg_mokojoomcross_twitter — X/Twitter API v2
• plg_mokojoomcross_linkedin — LinkedIn Share API
• plg_mokojoomcross_mastodon — Mastodon API
• plg_mokojoomcross_bluesky — Bluesky AT Protocol
• plg_mokojoomcross_mailchimp — Mailchimp Campaigns API
• plg_mokojoomcross_telegram — Telegram Bot API (default @MokoWaaSBot + custom bot)
• plg_mokojoomcross_discord — Discord Webhooks
• plg_mokojoomcross_slack — Slack Incoming Webhooks

Database Schema

Four tables:

#__mokojoomcross_services:

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

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

#__mokojoomcross_templates:

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

#__mokojoomcross_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 MokoJoomCrossServiceInterface