3

api-index

Jonathan Miller edited this page 2026-05-20 01:26:18 +00:00

Table of Contents

• API Documentation
• Overview
• Directory Structure
• Purpose
• Documentation Conventions
• File Organization
• Naming Conventions
• Documentation Structure
• API Directories
• automation/
• definitions/
• validate/
• lib/
• build/
• release/
• tests/
• cli/
• deploy/
• plugin/
• maintenance/
• analysis/
• wrappers/
• Quick Start
• Repository Validation
• Plugin System
• Deployment
• Bulk Sync
• Development Guidelines
• Architecture
• Plugin System
• Enterprise Libraries
• Validation Pipeline
• Related Documentation

← Home

API Documentation

Overview

This directory contains documentation for the moko-platform API structure. The documentation mirrors the actual API directory structure found in /api/.

Directory Structure

docs/api/
├── index.md                    # This file - API documentation overview
├── analysis/                   # Analysis tools documentation
├── automation/                 # Automation scripts (bulk_sync.php)
├── build/                      # Build tools documentation
├── definitions/                # Repository definitions documentation
│   ├── default/               # Default platform definitions documentation
│   └── sync/                  # Synced repository definitions documentation
├── cli/                       # Repo lifecycle & release scripts
├── deploy/                    # Deploy scripts (deploy-sftp.php, deploy-joomla.php)
├── fix/                       # Fix utilities (fix_*.php)
├── lib/                       # Library documentation
│   ├── Enterprise/            # Enterprise libraries
│   └── plugins/               # Plugin system
├── maintenance/               # Maintenance scripts documentation
├── plugin/                    # Plugin runner scripts (plugin_*.php)
├── release/                   # Release tools documentation
├── tests/                     # Testing documentation
├── validate/                  # Validation scripts (check_*.php)
└── wrappers/                  # Wrapper scripts documentation

Purpose

The API directory (/api/) contains all core functionality for:

• Repository validation - Scripts to validate repository structure and compliance
• Automation - Bulk sync and automated repository management
• Definitions - Repository structure definitions for different platforms
• Enterprise libraries - Reusable PHP libraries for GitHub API, logging, metrics
• Build and release - Tools for building and releasing projects
• Analysis - Code analysis and quality tools
• Testing - Test infrastructure and utilities

Documentation Conventions

File Organization

• Each API directory has corresponding documentation in api/
• Documentation files use .md (Markdown) format
• Index files (index.md) provide directory overview
• Individual scripts/tools have dedicated documentation files

Naming Conventions

Documentation files follow these patterns:

• index.md - Directory overview and contents listing
• {script-name}.md - Documentation for specific script
• {library-name}.md - Documentation for specific library
• overview.md - Conceptual overview for complex subsystems

Documentation Structure

Each documentation file should include:

1. Title and Purpose - What the component does
2. Usage - How to use it (command-line examples, API calls)
3. Parameters/Options - Detailed parameter documentation
4. Examples - Real-world usage examples
5. Output - What to expect from the command/function
6. Related - Links to related documentation

API Directories

automation/

Automation scripts for bulk repository operations:

• bulk_sync.php - Bulk synchronization across multiple repositories
• Repository definition generation
• Automated PR creation and management

View automation documentation →

definitions/

Repository structure definitions:

• default/ - Platform-specific base definitions
• sync/ - Auto-generated repository-specific definitions

View definitions documentation →

validate/

Validation and compliance checking:

• auto_detect_platform.php - Platform detection and validation
• check_repo_health.php - Repository health scoring
• check_enterprise_readiness.php - Enterprise readiness validation

View validation documentation →

lib/

Reusable library components:

• Enterprise/ - GitHub API client, logging, metrics, synchronization
• plugins/ - Plugin system for platform-specific operations

View library documentation →

build/

Build tools and utilities:

• Build automation scripts
• Dependency management
• Asset compilation

View build documentation →

release/

Release management tools:

• Package generation scripts
• Platform-specific packaging (Joomla, Dolibarr)
• Version management

View release documentation →

tests/

Testing infrastructure:

• Unit tests
• Integration tests
• Test utilities and helpers

View testing documentation →

cli/

Repository lifecycle and release management scripts:

• create_repo.php — Scaffold new governed repositories (7-step wizard: create, topics, .mokostandards, README, labels, sync, project)
• archive_repo.php — Graceful retirement: close PRs/issues, archive on GitHub, remove sync definition
• release.php — Create version releases and version branches (version/XX)
• sync_rulesets.php — Apply org rulesets (MAIN, DEV, VERSION, RC, WORKFLOWS) to repos
• platform_detect.php — Detect repo platform type (crm-module, waas-component, crm-platform, generic)
• version_bump.php — Bump version numbers across all files
• version_read.php — Read current version from repo
• create_project.php — Create GitHub Project for a repo

deploy/

SFTP deployment scripts:

• deploy-sftp.php — Upload a repo's src/ or htdocs/ to a remote server via SFTP
• deploy-joomla.php — Smart Joomla deploy: parses XML manifest, routes files to correct Joomla directories
• Supports PuTTY .ppk and OpenSSH PEM keys
• Called by deploy-dev.yml and deploy-demo.yml workflows (deploy-rs.yml retired)

View deploy documentation →

plugin/

Plugin-system runner scripts (entry points for governed repos):

• plugin_validate.php — Validate project structure and standards
• plugin_health_check.php — Run health checks and score
• plugin_readiness.php — Check release readiness
• plugin_metrics.php — Collect project metrics
• plugin_list.php — List all registered project-type plugins

View plugin script documentation →

maintenance/

Maintenance and housekeeping scripts:

• pin_action_shas.php — Pin Gitea Actions to immutable SHAs
• setup_labels.php — Deploy 67 required GitHub labels (12 groups)
• sync_dolibarr_readmes.php — Keep root and src READMEs in sync
• update_sha_hashes.php — Regenerate script registry hashes
• update_version_from_readme.php — Propagate version from README
• rotate_secrets.php — Audit FTP secrets/variables across repos
• repo_inventory.php — Live inventory dashboard as GitHub issue

View maintenance documentation →

analysis/

Code analysis tools:

• Static analysis
• Quality metrics
• Dependency analysis

View analysis documentation →

wrappers/

Shell wrappers for cross-platform compatibility:

• bash/ - Bash wrapper scripts

View wrappers documentation →

Quick Start

Repository Validation

# Auto-detect platform and validate repository
php api/validate/auto_detect_platform.php --path /path/to/repo

# Check repository health score
php api/validate/check_repo_health.php --path /path/to/repo

# Check all validation scripts at once
php api/validate/check_repo_health.php --path . --json

Plugin System

# Validate a project
php api/plugin_validate.php --project-path /path/to/project

# Check release readiness
php api/plugin_readiness.php --project-path /path/to/project

# Run health check
php api/plugin_health_check.php --project-path /path/to/project

# List all registered plugins
php api/plugin_list.php

Deployment

# Preview SFTP upload (dry-run)
php api/deploy/deploy-sftp.php --path /path/to/project --dry-run --verbose

# Deploy src/ to remote server
php api/deploy/deploy-sftp.php --path /path/to/project

Bulk Sync

# Sync templates to multiple repositories
php api/automation/bulk_sync.php \
  --org MokoConsulting \
  --repos "repo1,repo2,repo3"

Development Guidelines

When developing new API components:

1. Follow existing patterns - Use established conventions
2. Add documentation - Create corresponding docs/api/ documentation
3. Include examples - Provide real-world usage examples
4. Handle errors - Implement proper error handling and logging
5. Write tests - Add test coverage for new functionality
6. Use type hints - Declare strict types in PHP code
7. Log operations - Use AuditLogger for important operations

Architecture

Plugin System

The API uses a plugin architecture for platform-specific operations:

// Auto-detect platform and create plugin
$detector = new ProjectTypeDetector($repoPath);
$projectType = $detector->detect();
$plugin = PluginFactory::createForProject($repoPath);

// Use plugin for platform-specific operations
$health = $plugin->healthCheck();
$metrics = $plugin->collectMetrics();

Enterprise Libraries

Core enterprise libraries provide:

• ApiClient - GitHub API client with rate limiting and circuit breaker
• AuditLogger - Structured logging with transaction support
• MetricsCollector - Metrics collection and reporting
• RepositorySynchronizer - Repository synchronization logic

Validation Pipeline

Repository validation follows this pipeline:

1. Platform Detection - Identify repository type
2. Definition Loading - Load appropriate structure definition
3. Structure Validation - Validate against definition
4. Health Scoring - Calculate health score (0-100+)
5. Report Generation - Generate validation report

Related Documentation

• Validation Guide - Complete validation documentation
• Automation Guide - Automation workflows and processes
• Schema Guide - Repository structure schemas
• Development Guide - Development guidelines and standards

---

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	moko-platform

Revision	Date	Author	Description
1.0	2026-05-08	Moko Consulting	Initial version