#	Principle	Description
1	Separation of Concerns	Each module has a single, well-defined responsibility
2	Type Safety	Full type hints on all public interfaces
3	Error Handling	Comprehensive error messages with actionable guidance
4	Documentation	Docstrings following Google style guide
5	Testability	All modules designed for unit testing with clear interfaces
6	Logging	Structured logging with consistent levels and formats
7	Configuration	Centralized configuration management
8	Dependencies	Minimal external dependencies, clear dependency tree

Module Hierarchy

scripts/
├── lib/                         # Core libraries (no external script dependencies)
│   ├── common.py               # Foundation: constants, utilities, decorators
│   ├── validation_framework.py  # Base classes for validators
│   ├── config_manager.py       # Configuration handling
│   ├── github_client.py        # GitHub API wrapper
│   ├── audit_logger.py         # Structured logging
│   ├── extension_utils.py      # Extension/package utilities
│   ├── joomla_manifest.py      # Joomla-specific manifest handling
│   └── gui_utils.py            # GUI utilities (optional)
│
├── validate/                    # Validation scripts (depend on lib/)
│   ├── auto_detect_platform.php # Platform detection (core)
│   ├── validate_structure_v2.py # Structure validation
│   ├── validate_repo_health.py  # Repository health
│   ├── schema_aware_health_check.py  # Schema-based validation
│   ├── check_repo_health.py     # Health checker
│   ├── validate_codeql_config.py # CodeQL validation
│   ├── manifest.py              # Manifest validation
│   ├── workflows.py             # Workflow validation
│   ├── php_syntax.py            # PHP syntax checking
│   ├── xml_wellformed.py        # XML validation
│   ├── no_secrets.py            # Secret detection
│   ├── tabs.py                  # Tab/whitespace checking
│   ├── paths.py                 # Path validation
│   └── generate_stubs.py       # Stub generation
│
├── automation/                  # Automation scripts (depend on lib/, validate/)
│   ├── bulk_update_repos.php (v2)  # Bulk repository sync
│   ├── auto_create_org_projects.py  # Organization project automation
│   ├── sync_dolibarr_changelog.py   # Dolibarr changelog sync
│   ├── sync_file_to_project.py      # File sync to projects
│   ├── create_repo_project.py       # Repository project creation
│   └── file-distributor.py          # File distribution
│
├── release/                     # Release management (depend on lib/, validate/)
│   ├── detect_platform.py      # Platform detection for releases
│   ├── package_extension.py    # Extension packaging
│   └── dolibarr_release.py     # Dolibarr release management
│
├── maintenance/                 # Maintenance scripts (depend on lib/)
│   ├── release_version.py      # Version management
│   ├── update_changelog.py     # Changelog updates
│   ├── validate_file_headers.py # Header validation
│   └── flush_actions_cache.py  # Actions cache management
│
├── analysis/                    # Analysis tools (depend on lib/)
│   ├── analyze_pr_conflicts.py # PR conflict analysis
│   └── generate_canonical_config.py  # Canonical configuration
│
├── build/                       # Build scripts (depend on lib/)
│   └── resolve_makefile.py     # Makefile resolution
│
├── docs/                        # Documentation generation (depend on lib/)
│   └── rebuild_indexes.py      # Index rebuilding
│
├── run/                         # Runtime scripts (depend on lib/, automation/)
│   └── setup_github_project_v2.py  # GitHub Project v2 setup
│
└── tests/                       # Test scripts
    ├── test_bulk_update_repos.php  # Bulk update tests
    └── test_dry_run.py            # Dry run tests

Core Library Modules (`lib/`)

common.py

Purpose: Foundation module with core utilities

Constants (VERSION dynamically read from README.md, REPO_URL, EXIT codes)
File header generation
Logging utilities and error handling decorators
Path utilities and version extraction

validation_framework.py

Purpose: Base classes and interfaces for validation

Validator base class, ValidationResult data class
ValidationRule interface, common validation patterns

config_manager.py

Purpose: Centralized configuration management

ConfigManager class with schema validation
Environment variable handling and defaults

github_client.py

Purpose: GitHub API wrapper with authentication

GitHubClient class with retries and rate limit management

audit_logger.py

Purpose: Structured logging framework

AuditLogger class with level management and structured formatting

Validation Modules (`validate/`)

All validation modules follow the pattern:

Import from lib/
Define validation rules
Implement Validator interface
Return ValidationResult objects
Provide CLI interface

auto_detect_platform.php

Critical Module -- Platform detection for all automation.

Dependencies: lib/common, lib/validation_framework
Exports: detect_platform(), PlatformType enum

Automation Modules (`automation/`)

Script	Status	Purpose
`bulk_update_repos.php` (v2)	Rebuilt 2026-01-19	Schema-driven bulk repository synchronization
`auto_create_org_projects.py`	Active	Automated organization project creation

Workflows (`.gitea/workflows/`)

Category	Purpose
CI/CD	Build, test, deploy workflows
Quality	Code quality, linting, validation
Automation	Bulk updates, project management
Security	Secret scanning, CodeQL, confidentiality
Maintenance	Cache management, changelog updates

Coding Standards

Python

Area	Standard
Style	PEP 8 compliant
Type Hints	Required for all public functions
Docstrings	Google style, required for all public functions
Error Handling	Use specific exception types
Logging	Use `audit_logger`
Testing	Unit tests for all public functions

YAML (Workflows)

Naming: kebab-case for file names
Indentation: 2 spaces
Secrets: Use repository/organization secrets, never hardcode
Permissions: Minimal required permissions only

File Header Standard

#!/usr/bin/env python3
# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# FILE INFORMATION
# DEFGROUP: [Group]
# INGROUP: [Parent Group]
# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
# PATH: [Relative path from repo root]
# VERSION: [X.Y.Z]
# BRIEF: [One-line description]

Note

: The VERSION constant in common.py and MOKO_VERSION in common.sh are dynamically extracted from the README.md title line. This ensures a single source of truth.

Error Handling

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	File/resource not found
`4`	Permission error
`5`	Validation failed
`6`	External dependency error

Error Message Format

[LEVEL] Component: Message (Context)

Testing Strategy

Unit tests in scripts/tests/ using pytest, 80%+ coverage target
Integration tests end-to-end with test repositories
Validation tests for all validators (valid + invalid inputs + edge cases)

Configuration Hierarchy

Command-line arguments (highest priority)
Environment variables
Configuration files (MokoStandards.override.xml)
Default values (lowest priority)

Validated against schemas/unified-repository-schema.json.

Dependencies

Type	Packages
Required	None (stdlib only for core modules)
Optional	`requests` (GitHub API), `PyYAML` (YAML parsing), `pytest` (dev only)

pip install -r requirements.txt        # Production
pip install -r requirements-dev.txt    # Development

Security

No Hardcoded Secrets -- use Gitea secrets
Input Validation -- validate all user inputs
Path Traversal Prevention -- validate all file paths
Least Privilege -- minimal permissions in workflows

WORKFLOW_STANDARDS -- Workflow coding standards
Documentation-Standards -- Documentation conventions
DRY_RUN_PATTERN -- Standard dry-run pattern
MINIFICATION -- Asset minification pipeline

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	All repositories

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

Platform Scripts Architecture

Overview

Design Principles