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.

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
│   └── update-server.md        # Update server configuration
├── scripts/                    # Build and deployment scripts
├── updates.xml                 # Joomla update server manifest
├── 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:

• auto-assign.yml — Auto-assign issues/PRs to jmiller
• auto-dev-issue.yml — Create tracking issue on dev branch push
• auto-release.yml — Create GitHub Release on main merge
• changelog-validation.yml — Validate CHANGELOG.md format
• ci-joomla.yml — Joomla manifest validation, XML lint
• codeql-analysis.yml — Security scanning
• copilot-agent.yml — Copilot agent configuration
• deploy-manual.yml — Manual FTP deploy for testing
• enterprise-firewall-setup.yml — Copilot firewall rules
• project-setup.yml — Initialize project structure
• repo_health.yml — Repository health checks
• repository-cleanup.yml — Clean up stale branches/artifacts
• standards-compliance.yml — MokoStandards validation
• sync-version-on-merge.yml — Version tracking
• update-docs.yml — Auto-update documentation indexes
• update-server.yml — Update updates.xml on release

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

Update Server

Client repos use the standard dual update server with Gitea as priority 1:

<updateservers>
  <server type="extension" priority="1" name="{ExtName} (Gitea)">
    https://git.mokoconsulting.tech/MokoConsulting/client-{name}/raw/branch/main/updates.xml
  </server>
  <server type="extension" priority="2" name="{ExtName} (GitHub)">
    https://raw.githubusercontent.com/mokoconsulting-tech/client-{name}/main/updates.xml
  </server>
</updateservers>

Deployment

Client sites are deployed via:

1. Joomla updater — site pulls from updates.xml (preferred for production)
2. Manual FTP — via deploy-manual.yml workflow dispatch (for dev/staging)
3. 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-*)
• Extra workflows: project-setup.yml, update-docs.yml, copilot-agent.yml
• SFTP config: sftp-config.json.template with credential placeholders
• Branding: Client-specific (not Moko Consulting)
• Deployment: Joomla updater + manual FTP (standard repos use updater only)