PolyCMS Architecture Overview

MVC Architecture

PolyCMS follows strict Model-View-Controller architecture built on CodeIgniter - the same framework powering Perfex CRM. This ensures seamless integration with the CRM's existing codebase and conventions.

File Structure

modules/polycms/
├── polycms.php                            # Main module bootstrap & hook entry point
├── install.php                            # Database installer (19 tables) & defaults
├── uninstall.php                          # Module uninstaller & cleanup script
├── config/
│   ├── my_routes.php                      # Dynamic routing engine with blog prefix rules
│   └── csrf_exclude_uris.php              # REST API CSRF exclusion rules
├── controllers/                           # MVC Controllers
│   ├── Admin.php                          # PolyCMS admin dashboard & stats
│   ├── Api.php                            # Comprehensive REST API controller
│   ├── Api_explorer.php                   # Interactive API Explorer sandbox
│   ├── Banner_slider.php                  # Banner Slider admin controller
│   ├── Categories.php                     # Hierarchical Category tree CRUD
│   ├── Comments.php                       # Comment moderation controller
│   ├── Frontend.php                       # Public frontend renderer (Single, Archive, Pages, Search, RSS)
│   ├── Media.php                          # Media Library manager & WebP uploader
│   ├── Menus.php                          # Drag-and-drop Navigation Menu Builder
│   ├── Mtbuilder.php                      # MTBuilder Visual Page Builder controller
│   ├── Pages.php                          # Static CMS Pages CRUD & template manager
│   ├── Permalink_settings.php             # Permalink structures & 301 redirection manager
│   ├── Plugins.php                        # Plugin management (ZIP install, activate, settings)
│   ├── Posts.php                          # Blog Post CRUD, TinyMCE, SEO, scheduled publishing
│   ├── Settings.php                       # Core CMS settings (General, Reading, SEO, Discussion)
│   ├── Tags.php                           # Post tags CRUD & usage metrics
│   ├── Theme_options.php                  # Live Theme Customizer & options storage
│   ├── Themes.php                         # Theme management (ZIP install, switcher)
│   ├── Tools.php                          # WXR/JSON Import/Export, DB backup/restore, Demo generator
│   └── Widgets.php                        # Drag-and-drop Widget Area manager
├── models/                                # Database Models (Active Record)
│   ├── Blog_post_model.php                # Posts DB queries, pagination, search, filters
│   ├── Blog_category_model.php            # Categories hierarchy tree model
│   ├── Blog_tag_model.php                 # Tags taxonomy & cloud generator model
│   ├── Blog_comment_model.php             # Comments nested threading model
│   ├── Blog_page_model.php                # Pages model & custom fields
│   ├── Blog_menu_model.php                # Menus & nested item reordering model
│   ├── Blog_plugin_model.php              # Plugins status & options model
│   ├── Blog_theme_model.php               # Themes status & headers model
│   ├── Blog_widget_model.php              # Widgets & area instances model
│   └── Blog_media_model.php               # Media dimensions, mime types & file sync model
├── libraries/                             # Service Libraries
│   ├── Blog_hooks.php                     # WordPress-style Action & Filter hook engine
│   ├── Blog_plugin_loader.php             # Plugin header parser & security scanner
│   ├── Blog_theme_loader.php              # Theme header parser & template hierarchy
│   ├── Blog_shortcode.php                 # Shortcode registry & recursive parser
│   ├── Blog_widget.php                    # Widget base class & area registry
│   ├── Polycms_Asset_Manager.php          # Asset enqueue manager for CSS/JS
│   ├── Polycms_Integration.php            # Perfex CRM core integration & homepage router
│   └── Polycms_Rate_Limiter.php           # IP-based rate limiter library
├── plugins/                               # 7 Built-in Plugins
│   ├── mtbuilder/                         # MT Studio Visual Page Builder
│   ├── mtoptimize/                        # Performance, Minification & Cache Optimizer
│   ├── banner-slider/                     # Responsive Hero Banner Slider
│   ├── api-explorer/                      # Interactive REST API Explorer Sandbox
│   ├── google-analytics/                  # Google Analytics GA4 / GTM Tracking
│   ├── maintenance-mode/                  # Frontend Maintenance & Coming Soon Mode
│   └── xml-sitemap/                       # Automatic XML Sitemap Generator
├── themes/                                # Themes Ecosystem
│   └── head-random/                       # Head Random Production Theme
├── widgets/                               # 9 Built-in Widget Classes
└── shortcodes/                            # 3 Built-in Shortcode Handlers

Database Schema (19 Relational Tables)

PolyCMS creates 19 dedicated tables, all prefixed with your Perfex CRM table prefix + blog_:

All tables use proper foreign key constraints and InnoDB indexes for optimal query performance. CMS data is completely isolated from CRM client data.

Request Lifecycle

Admin Requests

1. Perfex CRM routes request to PolyCMS controller.
2. Controller validates staff_can() permissions.
3. Controller calls Model for database operations.
4. Model returns data via CodeIgniter Active Record.
5. Controller loads admin View with data.

Frontend Requests

1. Dynamic routing system matches URL against permalink patterns.
2. Frontend.php controller determines content type (post, page, category, tag, search, archive).
3. Hooks fire: polycms_frontend_init, polycms_head.
4. Blog_theme_loader resolves template hierarchy -> selects appropriate theme template.
5. Template renders with data, widgets, and shortcodes processed.
6. Hooks fire: polycms_footer.

Plugin System Architecture

Plugins are loaded by the Blog_plugin_loader during module initialization:

1. Scan plugins/ directory for plugin.json manifests.
2. Check activation status in blog_plugins table.
3. Load active plugin main files.
4. Plugins register hooks via polycms_add_action() and polycms_add_filter().
5. Hooks fire at appropriate lifecycle points during request processing.

Theme System Architecture

The Blog_theme_loader handles template resolution:

1. Check active theme in blog_themes table.
2. Determine content type from current request.
3. Walk template hierarchy: single.php -> category.php -> tag.php -> page.php -> index.php.
4. Load first matching template file from active theme directory.
5. Pass content data, widgets, and theme options to template scope.

Security Architecture

• Permission Layer - All admin actions gated by staff_can('polycms', ...).
• XSS Protection - HTMLPurifier sanitizes all rich-text content.
• SQL Protection - CodeIgniter Active Record / Query Builder prevents injection.
• File Protection - polycms_validate_file_path prevents directory traversal.
• Rate Limiting - IP-based cache limiter on public endpoints.
• BASEPATH Guard - Every PHP file includes defined('BASEPATH') or exit().

Related Documentation

• Hooks & Filters Reference - Complete hook API documentation.
• Building a Custom Plugin - Plugin development guide with sample code.
• Building a Custom Theme - Theme development guide with template hierarchy.
• Template Tags & Helpers - Available helper functions for themes and plugins.