MokoCLI/docs/client-repos.md

Client Repository Standards

Overview

Client repos (client-*) contain Joomla site customizations for individual clients — templates, overrides, custom CSS, module configurations, and deployment scripts. They follow the Joomla workflow profile but have additional rules around privacy, branding, and deployment.

Note

: Client repos are sites, not distributable Joomla extensions. They do not have updates.xml or an update-server workflow.

Naming Convention

client-{clientname}

• Lowercase, hyphenated client identifier
• No version numbers in the repo name
• Examples: client-clarksvillefurs, client-kiddieland, client-vexcreations

Repository Structure

client-{name}/
├── .github/                    # Workflows, CLAUDE.md, CODEOWNERS
│   ├── workflows/              # Standard Joomla workflows (from template)
│   ├── CLAUDE.md               # AI assistant context for this client
│   └── CODEOWNERS              # jmiller owns all files
├── src/                        # Joomla extension source
│   ├── templates/              # Template overrides
│   ├── modules/                # Custom modules
│   ├── plugins/                # Custom plugins
│   └── media/                  # CSS, JS, images
├── docs/                       # Client-specific documentation
│   └── INSTALLATION.md         # Deployment instructions
├── scripts/                    # Build and deployment scripts
├── composer.json               # Dependencies
├── CHANGELOG.md                # Version history
├── README.md                   # Client overview (no sensitive details)
├── LICENSE                     # GPL-3.0-or-later
└── Makefile                    # Build targets

Privacy Rules

Client repos are private by default. These rules are non-negotiable:

1. No client credentials in the repo — passwords, API keys, FTP credentials, database passwords go in environment variables or secure secrets, never in code or config files
2. No PII — no customer names, emails, addresses, phone numbers in code or comments
3. No client-specific hostnames in committed configs — use environment variables or sftp-config.json.template patterns with placeholders
4. README.md is generic — describes the extension type, not the client's business details
5. CLAUDE.md may reference the client by name for AI context, but must not include credentials

Workflows

Client repos use the Joomla workflow profile from MokoStandards-Template-Client (10 workflows):

• auto-release.yml — Create GitHub Release on main merge
• pre-release.yml — Pre-release builds for dev/rc branches
• ci-joomla.yml — Joomla manifest validation, XML lint
• pr-check.yml — Pull request validation
• deploy-manual.yml — Manual FTP deploy for testing
• repo-health.yml — Repository health checks
• security-audit.yml — Security scanning
• notify.yml — Notifications for workflow events
• cleanup.yml — Clean up stale branches/artifacts
• sync-media.yml — Synchronize media assets

Release Tags

Standard 5-tag system applies:

• development — Dev builds
• alpha — Internal testing
• beta — Client preview / UAT
• release-candidate — Final QA before production
• stable — Production release

Deployment

Client sites are deployed via:

1. Manual FTP — via deploy-manual.yml workflow dispatch (for dev/staging)
2. Direct install — download ZIP from GitHub Release and install via Joomla admin

Creating a New Client Repo

1. Create from template: MokoStandards-Template-Client
2. Name it client-{clientname} (lowercase, hyphenated)
3. Set repo to private
4. Set up secrets: GA_TOKEN, GH_TOKEN
5. Configure push mirror to GitHub
6. Apply branch protection on main
7. Update README.md, composer.json, CLAUDE.md with client-specific context
8. Run initial bulk sync to pull latest standards

Differences from Standard Joomla Repos

• Visibility: Always private (standard Joomla repos can be public)
• Template: MokoStandards-Template-Client (not Template-Joomla-*)
• No updates.xml: Client repos are sites, not distributable extensions
• SFTP config: sftp-config.json.template with credential placeholders
• Branding: Client-specific (not Moko Consulting)
• Deployment: Manual FTP + direct install (standard repos use Joomla updater)