# API Documentation

## Overview

This directory contains documentation for the MokoStandards 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 `docs/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 →](./automation/index.md)

### definitions/

Repository structure definitions:

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

[View definitions documentation →](./definitions/default/index.md)

### 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 →](./validate/index.md)

### lib/

Reusable library components:

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

[View library documentation →](./lib/index.md)

### build/

Build tools and utilities:

- Build automation scripts
- Dependency management
- Asset compilation

[View build documentation →](./build/index.md)

### release/

Release management tools:

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

[View release documentation →](./release/index.md)

### tests/

Testing infrastructure:

- Unit tests
- Integration tests
- Test utilities and helpers

[View testing documentation →](./tests/index.md)

### 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 →](./deploy/index.md)

### 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 →](./plugin/index.md)

### maintenance/

Maintenance and housekeeping scripts:

- **pin_action_shas.php** — Pin GitHub 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 →](./maintenance/index.md)

### analysis/

Code analysis tools:

- Static analysis
- Quality metrics
- Dependency analysis

[View analysis documentation →](./analysis/index.md)

### wrappers/

Shell wrappers for cross-platform compatibility:

- **bash/** - Bash wrapper scripts

[View wrappers documentation →](./wrappers/index.md)

## Quick Start

### Repository Validation

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

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

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

```bash
# Sync templates to multiple repositories
php api/automation/bulk_sync.php \
  --org mokoconsulting-tech \
  --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:

```php
// 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](../guide/validation/) - Complete validation documentation
- [Automation Guide](../automation/) - Automation workflows and processes
- [Schema Guide](../schemas/repohealth/) - Repository structure schemas
- [Development Guide](../development/) - Development guidelines and standards

---

**Location**: `docs/api/`  
**Purpose**: Documentation for MokoStandards API  
**Mirrors**: `/api/` directory structure  
**Last Updated**: 2026-04-04
**Maintained By**: MokoStandards Team