Document Type: Standard
Status: Active
Authority: HeadOffice
Applies To: All MWMS WordPress plugins, PHP modules, Brain UI systems, Supabase integrations
Parent: Governance
Version: v1.0
Last Reviewed: 2026-04-28
Purpose
This standard defines the required file and folder structure for all MWMS plugins.
Its purpose is to ensure:
• consistent plugin architecture
• easy navigation of files
• clear separation of responsibilities
• faster debugging
• safe updates and replacements
• compatibility with AI-assisted development
• reduced system complexity over time
Without a defined structure, plugins become difficult to manage, modify, and scale.
Scope
This standard applies to:
• all WordPress plugins in MWMS
• all Brain plugins (Affiliate, Research, etc.)
• admin UI pages
• Supabase integration files
• PHP helper modules
• action handlers
• render logic
It governs how files are structured and organised.
It does not govern:
• business logic decisions
• Brain authority rules
• UI design standards
• Canon governance
Core Principle
Every file must have a single clear responsibility and a predictable location.
A developer must always know:
• where a page lives
• where data is saved
• where actions are handled
• where UI is rendered
• where external connections are made
If a file’s purpose is unclear, the structure is broken.
Standard Plugin Structure
All MWMS plugins must follow this structure:
plugin-root/
│
├── main-plugin-file.php
│
├── admin/
│ ├── pages/
│ ├── actions/
│ ├── render/
│ ├── helpers/
│ └── assets/
│
├── includes/
│
└── api/
Directory Definitions
1. Main Plugin File
Location:
plugin-root/main-plugin-file.php
Purpose:
• plugin header
• constant definitions
• file includes
• WordPress hooks
• initialization
Rules:
• must remain lightweight
• must not contain UI or business logic
• acts as system bootstrap only
2. admin/pages/
Purpose:
• full admin screens
• page-level logic
• layout control
Examples:
• opportunity-intake-queue.php
• opportunity-intake-record.php
Rules:
• handles screen-level structure only
• should not contain heavy data logic
• calls helpers for data
• calls render files for UI components
3. admin/actions/
Purpose:
• form submissions
• status updates
• save handlers
• POST request handling
Examples:
• opportunity-intake-save.php
• opportunity-status-update.php
Rules:
• no UI rendering
• only processes actions
• validates input
• updates data
• returns result or redirect
4. admin/render/
Purpose:
• reusable UI components
• cards
• tables
• panels
• structured display blocks
Examples:
• intake-card.php
• queue-table.php
Rules:
• contains HTML output only
• no business logic
• no database calls
5. admin/helpers/
Purpose:
• data access
• Supabase queries
• formatting helpers
• utility functions
Examples:
• intake-data.php
• supabase-client.php
Rules:
• handles all data operations
• isolates external calls
• reusable across pages
6. admin/assets/
Purpose:
• CSS loaders
• JS loaders
Examples:
• css-loader.php
• js-loader.php
Rules:
• enqueue scripts/styles
• no UI logic
7. includes/
Purpose:
• shared classes
• routing logic
• base utilities
• cross-module helpers
Examples:
• class-router.php
• class-base-render.php
Rules:
• reusable across plugin
• not tied to a single page
8. api/
Purpose:
• REST endpoints
• external integrations
• webhook handlers
Examples:
• endpoint-save.php
• endpoint-fetch.php
Rules:
• isolated from admin UI
• handles API requests only
Responsibility Separation Rule
Each file must do ONE job:
• page
• action
• render
• data
• API
• helper
Never mix:
• UI + data logic
• UI + API calls
• actions + rendering
File Naming Rules
All file names must:
• use lowercase
• use hyphen separation
• clearly describe purpose
Correct:
opportunity-intake-queue.php
opportunity-intake-save.php
intake-data-helper.php
Incorrect:
queue.php
file1.php
test-new.php
stuff.php
Function Naming Rules
Functions must include:
• system prefix
• Brain reference
• clear purpose
Example:
mwms_affiliate_render_intake_queue()
mwms_affiliate_save_intake_record()
mwms_affiliate_get_intake_records()
File Growth Rule
If a file becomes:
• too long to read easily
• difficult to edit
• contains multiple responsibilities
It must be split.
Edit Safety Rule
All files must be structured so they can be:
• fully replaced safely
• edited in isolation
• debugged independently
Preferred edit targets:
• entire file
• single function
• single class
Avoid:
• scattered edits across multiple files
Supabase Integration Rule
All Supabase interactions must:
• live in helper files
• use consistent naming
• not be embedded directly in UI
Pattern:
Page → Helper → Supabase
UI Rendering Rule
UI output must be:
• separated from logic where possible
• reusable across pages
• predictable in structure
Action Handling Rule
All actions must:
• validate input
• enforce allowed states
• return clear result
• not silently fail
Debugging Rule
A developer must be able to:
• identify issue location quickly
• isolate file causing issue
• replace file without breaking system
If debugging requires guessing, structure is incorrect.
Phase Discipline
File structure must not expand prematurely.
Phase 1:
• only intake-related files
• no research files
• no finance files
• no dashboards
• no automation
Governance Role
This standard ensures:
• plugin builds remain clean
• structure is predictable
• updates are safe
• debugging is fast
• AI collaboration is reliable
Relationship To Other MWMS Standards
This standard works with:
• MWMS Plugin Build Coordination Standard
• MWMS PHP Build And Modularity Standard
• MWMS Supabase Naming Standard
• MWMS AI Output Standard Full File Delivery Rule
Drift Protection
The system must prevent:
• random file placement
• unclear file responsibilities
• mixing UI and data logic
• oversized plugin files
• inconsistent naming
• hidden dependencies
• duplicated logic across files
Architectural Intent
This standard ensures that:
MWMS plugins remain:
• modular
• understandable
• scalable
• easy to maintain
• safe to update
It converts plugin development from:
unstructured file chaos
→
clear system architecture
Change Log
Version: v1.0
Date: 2026-04-28
Author: HeadOffice
Change:
Initial creation of MWMS Plugin File Structure Standard defining folder hierarchy, file responsibilities, naming rules, modular separation, and debugging discipline for all MWMS plugins.