# 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](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteCross/wiki) |
| **Standards** | [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) |

## Common Commands

```bash
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
```

```bash
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](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)

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