3

api-definitions-sync-index

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

Table of Contents

• Synced Repository Definitions
• Overview
• Purpose
• File Naming Convention
• File Format
• Generation Process
• Benefits
• Centralized Management
• Audit Trail
• Validation & Health Checks
• Clean Remote Repositories
• Usage
• Validation Scripts
• Health Checks
• Manual Review
• Maintenance
• Cleaning Stale Definitions
• Updating Definitions
• Git Tracking
• Migration Notes
• From Previous Approach
• Existing Override Files
• Related Documentation

← Home

Synced Repository Definitions

Overview

This directory contains auto-generated repository structure definitions created during bulk synchronization operations. Each synced repository gets its own definition file that captures its detected platform, structure, and configuration.

Purpose

When the bulk sync process runs, it:

1. Detects the repository platform (Joomla, Dolibarr, Node.js, etc.)
2. Generates a repository-specific definition based on the detected platform
3. Saves the definition in this directory as {repo}.def.tf
4. Uses the definition for validation and health checks

This replaces the previous approach of creating .github/override.tf files in remote repositories.

File Naming Convention

Files are named using the pattern: {repository}.def.tf

The .def.tf extension follows Terraform conventions where:

• .tf indicates Terraform HCL format
• .def indicates this is a definition/configuration file
• Follows Terraform protocol standards for module and configuration naming

Examples:

• MokoDoliCGAdClaude.def.tf - Dolibarr CRM module
• joomla-component-example.def.tf - Joomla component
• nodejs-api.def.tf - Node.js API project

File Format

Each definition file uses Terraform HCL format (.tf extension) with the same structure as files in api/definitions/default/:

/**
 * Repository Definition: {org}/{repo}
 * Auto-generated during bulk sync on {date}
 * Platform: {platform}
 * Repository Type: {type}
 */

locals {
  repository_structure = {
    metadata = {
      name             = "{Repository Name}"
      description      = "Repository structure for {org}/{repo}"
      repository_type  = "{type}"
      platform         = "{platform}"
      last_updated     = "{ISO8601 timestamp}"
      maintainer       = "{org}"
      version          = "1.0"
      schema_version   = "1.0"
      
      # Sync metadata
      sync_generated   = true
      sync_date        = "{ISO8601 timestamp}"
      source_repo      = "{org}/{repo}"
      detected_platform = "{platform}"
    }
    
    # Root files, directories, etc. inherited from platform definition
    # with repository-specific customizations
    ...
  }
}

Generation Process

During bulk sync:

1. Platform Detection: Auto-detect repository platform using auto_detect_platform.php
2. Load Base Definition: Load the appropriate base definition from api/definitions/default/
3. Customize Metadata: Add repository-specific metadata (org, repo name, sync date)
4. Save Definition: Write to api/definitions/sync/{org}-{repo}.tf
5. Skip Remote Override: Do NOT create .github/override.tf in the remote repository

Benefits

Centralized Management

• All repository definitions stored in moko-platform repository
• Easy to track changes and history through git
• No scattered override files across multiple repositories

Audit Trail

• Complete history of when repositories were synced
• Platform detection results preserved
• Changes to repository structure tracked in version control

Validation & Health Checks

• Health check scripts can reference these definitions
• Validation scripts can compare actual vs. expected structure
• Automated compliance monitoring across all repositories

Clean Remote Repositories

• No .github/override.tf files cluttering remote repos
• Remote repositories only receive templates and workflows
• Cleaner git history in remote repositories

Usage

Validation Scripts

Validation scripts automatically check both locations:

# Auto-detect platform and validate using synced definition if available
php api/validate/auto_detect_platform.php \
  --repo-path /path/to/repository \
  --repo repository-name

The script will:

1. Check for synced definition in api/definitions/sync/{repo}.def.tf
2. Fall back to platform-based definition in api/definitions/default/ if not found
3. Validate repository structure against the definition

Health Checks

# Run health check using synced definition
php api/validate/check_repo_health.php \
  --repo-path /path/to/repository \
  --repo repository-name

Manual Review

To review a synced repository's definition:

# View the definition
cat api/definitions/sync/MyRepo.def.tf

# Compare with base definition
diff api/definitions/default/default-repository.tf \
     api/definitions/sync/MyRepo.def.tf

Maintenance

Cleaning Stale Definitions

Periodically review and remove definitions for repositories that:

• Have been deleted
• Have been archived
• Are no longer being synced

# Find definitions for archived repositories
php api/maintenance/clean_stale_definitions.php --dry-run

Updating Definitions

Definitions are automatically regenerated on each bulk sync. To manually regenerate:

# Regenerate definition for a specific repository
php api/automation/bulk_sync.php \
  --repos MokoConsulting/MyRepo \
  --regenerate-definitions

Git Tracking

All files in this directory are tracked in git for complete audit trail and version control:

api/definitions/sync/
├── .gitignore           # Git configuration
├── README.md            # This documentation
└── *.def.tf            # All synced repository definitions (TRACKED)

This approach:

• ✅ Preserves complete history of all synced repositories
• ✅ Provides audit trail of definition changes over time
• ✅ Enables diff/review of repository structure changes
• ✅ Allows rollback to previous definition versions
• ✅ Documents which repositories are actively synced

Migration Notes

From Previous Approach

Previously, bulk sync created .github/override.tf files in each remote repository. This has been replaced with:

Old Approach:

Remote Repo: .github/override.tf (created by bulk sync)
moko-platform: templates/github/override.tf.template

New Approach:

Remote Repo: (no override file)
moko-platform: api/definitions/sync/{repo}.def.tf (auto-generated)

Existing Override Files

For repositories that already have .github/override.tf files:

• They will continue to work (not deleted)
• New syncs will not update them
• Health checks will prefer synced definitions in moko-platform
• Manual cleanup of old override files can be done separately

Related Documentation

• Default Definitions - Base platform definitions
• Schema Guide - Definition schema specification
• Bulk Sync Documentation - Bulk sync process
• Validation Guide - Platform detection and validation

---

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