Document Type: Standard
Status: Canon
Version: v1.0
Authority: HeadOffice
Applies To: All WordPress and PHP development within MWMS (Plus, Pro, contributors, future systems)
Parent: Governance
Last Reviewed: 2026-03-25
Purpose
This standard defines the required structural discipline for PHP and WordPress development across the MWMS ecosystem.
Its role is to:
prevent oversized files
reduce AI timeout risk
improve maintainability
improve debugging clarity
allow safe incremental edits
enable stable collaboration between humans and AI
maintain consistent architecture across Brains
reduce refactoring cost over time
support modular growth of the MWMS system
This standard ensures that PHP architecture decisions support long-term ecosystem scalability rather than short-term convenience.
Scope
Applies to:
WordPress plugins
WordPress MU plugins
admin UI modules
API handlers
router files
helper libraries
render functions
Supabase connectors written in PHP
AI executor connectors written in PHP
Brain UI modules
HeadOffice UI modules
SIT logging connectors
integration scripts
any PHP file used within MWMS
Core Principle
PHP files must remain modular, readable, and replaceable without requiring full-system rewrites.
Structure must support:
incremental improvement
safe testing
isolated debugging
predictable edits
low-risk AI collaboration
Consistency takes priority over speed.
Architectural Principle
Large files increase:
edit risk
merge conflicts
timeout probability
bug surface area
maintenance difficulty
cognitive load
Therefore:
Files should be separated by responsibility wherever practical.
Bootstrap files should remain small.
Functional logic should live in dedicated modules.
File Structure Standard
Preferred structure pattern:
main plugin file:
bootstrap only
constants
includes
hooks
initialisation
Example:
mwms-finance.php
mwms-research.php
mwms-sit.php
mwms-headoffice.php
Module Structure
Modules should be grouped by responsibility.
Example structure:
includes/
class-router.php
class-render.php
class-service.php
class-helpers.php
admin/
ui-screen.php
ui-cards.php
ui-layout.php
api/
endpoint-save.php
endpoint-fetch.php
assets/
css-loader.php
js-loader.php
Responsibility Separation Rule
Each file should ideally perform one role:
routing
rendering
data handling
helpers
UI structure
API handling
integration logic
Do not mix unrelated responsibilities inside one file unless strongly justified.
Bootstrap File Rule
Main plugin files should remain lightweight.
Preferred responsibilities:
define constants
load dependencies
register hooks
initialise modules
Bootstrap files should not contain large UI blocks or heavy business logic.
Edit Stability Rule
When modifying code, prefer stable replacement boundaries.
Preferred edit targets:
entire file replacement
single class replacement
single function replacement
clearly bounded code block replacement
Avoid requiring edits across multiple unrelated sections of a file.
Marker Comment Rule
Where modular separation is not yet practical, marker comments should be used to create stable edit boundaries.
Example:
// ===== START: Finance Dashboard Cards =====// code block// ===== END: Finance Dashboard Cards =====
AI instructions may then safely reference the block without relying on fragile line numbers.
Line Number Usage Rule
Line numbers may be used as a helper when:
the exact current file is provided
the edit is small
the edit affects a localised block
Line numbers must not be treated as the primary structural editing method.
Line numbers are volatile and may change after any modification.
Preferred reference targets:
function name
class name
marker comment block
file name
method name
Function-Level Replacement Rule
Where possible, edits should target individual functions or methods.
Example:
replace function render_dashboard_cards()
replace class MWMS_Finance_Router
add method register_assets()
This reduces risk and improves clarity.
File Size Guidance
As a general guideline:
If a file becomes difficult to review in one screen, consider splitting responsibilities.
If repeated edits affect unrelated parts of a file, modularisation is recommended.
If full file output becomes difficult due to size, the file should be separated.
Naming Discipline
File names should remain consistent with MWMS naming patterns.
Examples:
mwms-finance.php
class-finance-router.php
class-finance-render.php
research-template-affiliate.php
Avoid introducing inconsistent naming styles mid-system.
Naming must remain predictable across Brains.
AI Collaboration Compatibility
Files should be structured to support:
clear diff boundaries
isolated edits
predictable replacements
stable references
AI-assisted iteration
The system must support collaboration across:
ChatGPT Plus
ChatGPT Pro
future AI tools
human developers
Interaction with Supabase Standard
Where PHP interacts with Supabase:
naming must remain aligned with:
MWMS – Supabase Naming Standard
PHP structure must not introduce naming drift.
Relationship to Other Standards
This standard complements:
MWMS – Supabase Naming Standard
MWMS – Document Structure Standard
MWMS – Page Naming Standard
Brain Header Schema Standard
How to Start a Session – MWMS Operating Guide
This page does not override Brain-specific architecture rules.
Session Anchor Requirement
For WordPress or PHP build sessions, this page must be included in the startup anchor pack.
Recommended startup sequence:
How to Start a Session – MWMS Operating Guide
MWMS – PHP Build & Modularity Standard
relevant Brain Canon
target file or plugin
This ensures consistent technical structure across sessions.
Change Log
Version: v1.0
Date: 2026-03-25
Author: HeadOffice
Change: Initial creation of PHP modular architecture standard for MWMS WordPress and integration development. Establishes file separation discipline, edit boundary rules, line number guidance, marker block protocol, and AI collaboration compatibility framework.