PolyCMS Architecture Overview for RISE CRM
PolyCMS for RISE CRM is engineered as a native CodeIgniter 4 plugin following strict Model-View-Controller (MVC) separation inside {rise_crm_root}/plugins/polycms/. It pairs RISE CRM's Bootstrap 5 interface and hook system with a collision-proof compatibility layer, 19 isolated InnoDB database tables, dynamic permalink routing with a safe 404 override, and modular ecosystems for sub-plugins, themes, widgets, and shortcodes.
Plugin Directory Structure
All PolyCMS source code lives inside plugins/polycms/ using CodeIgniter 4's PascalCase directory conventions (Controllers/, Models/, Libraries/, Helpers/, Views/, Language/):
plugins/polycms/
├── index.php # Main bootstrap, RISE hooks, lifecycle hooks & sidebar registration
├── install/
│ └── database.sql # Idempotent InnoDB schema for all 19 blog_* tables
├── config/
│ └── Routes.php # CI4 routes: /polycms/*, /cms/api/v1/*, SEO, prefix & set404Override
├── Controllers/ # 22 CI4 MVC Controllers
│ ├── Base_admin_controller.php # Extends \App\Controllers\Security_Controller + BS5 layout bridge
│ ├── Base_public_controller.php # Extends \App\Controllers\App_Controller for frontend & REST API
│ ├── Admin.php # CMS Dashboard & overview metrics
│ ├── Api.php # Stateless REST API v1 controller
│ ├── Api_explorer.php # Interactive API Explorer sandbox
│ ├── Banner_slider.php # Banner Slider management controller
│ ├── Categories.php # Hierarchical category tree CRUD
│ ├── Comments.php # Comment moderation controller
│ ├── Frontend.php # Public frontend renderer, sitemaps, robots.txt & 404 catch-all
│ ├── Media.php # Media Library manager & uploader
│ ├── Menus.php # Drag-and-drop navigation menu builder
│ ├── Mtbuilder.php # MTBuilder visual page builder & template parts
│ ├── Pages.php # Static CMS pages CRUD
│ ├── Permalink_settings.php # Permalink structure & prefix cache manager
│ ├── Plugins.php # Sub-plugin discovery, ZIP upload, activation & settings
│ ├── Posts.php # Blog posts CRUD, scheduling & SEO fields
│ ├── Settings.php # 5-tab settings (Reading, General, Performance, Localization, API)
│ ├── Tags.php # Tags CRUD & merge tools
│ ├── Theme_options.php # Theme Customizer options storage
│ ├── Themes.php # Theme switcher & ZIP installer
│ ├── Tools.php # JSON Import/Export, SQL Backup/Restore & Demo Seeder
│ └── Widgets.php # Drag-and-drop widget area manager
├── Models/ # 10 Domain Models + Polycms_Base_Model.php
│ ├── Polycms_Base_Model.php # Base model bridge for CI4 DB Query Builder
│ ├── Blog_post_model.php
│ ├── Blog_page_model.php
│ ├── Blog_category_model.php
│ ├── Blog_tag_model.php
│ ├── Blog_comment_model.php
│ ├── Blog_media_model.php
│ ├── Blog_menu_model.php
│ ├── Blog_plugin_model.php
│ ├── Blog_theme_model.php
│ └── Blog_widget_model.php
├── Libraries/ # 9 Core Service Libraries
│ ├── Blog_hooks.php # Action & Filter hook dispatcher
│ ├── Blog_plugin_loader.php # Sub-plugin docblock header parser & loader
│ ├── Blog_theme_loader.php # Theme parser & template hierarchy resolver
│ ├── Blog_shortcode.php # Shortcode registry & recursive parser
│ ├── Blog_widget.php # Widget base class & sidebar/footer area registry
│ ├── Polycms_Asset_Manager.php # Frontend & admin asset manager
│ ├── Polycms_Integration.php # RISE CRM core integration & optional homepage redirect
│ ├── Polycms_Rate_Limiter.php # IP-based filesystem rate limiter
│ └── Polycms_Demo_Seeder.php # Onboarding & showcase content seeder
├── Helpers/ # Compatibility Bridge & Functional Helpers
│ ├── polycms_rise_compat_helper.php # Collision-proof RISE/CI4 helpers (polycms_ci, polycms_get_option...)
│ ├── CI3_Instance_Compat.php # CI3-to-CI4 singleton compatibility bridge
│ ├── CI3_DB_Wrapper.php # CI3 Active Record adapter over CI4 Query Builder
│ ├── CI3_Adapters.php # Input, URI, Session & Loader adapters
│ └── ... # Core, hooks, template, security, help, media, theme & plugin helpers
├── Views/ # Admin views (with rise_layout_bridge.php) & Frontend fallback views
├── Language/ # 16 bundled language packs
├── plugins/ # 7 bundled sub-plugins (mtbuilder, mtoptimize, xml-sitemap, etc.)
├── themes/ # Bundled Head Random Bootstrap 5 theme
├── widgets/ # 9 built-in widget classes
├── shortcodes/ # 3 built-in shortcode handlers
├── assets/ & dist/ # Self-hosted TinyMCE, Select2, SweetAlert2 & compiled bundles
└── vendor/ezyang/htmlpurifier/ # Plugin-local HTMLPurifier library
Runtime Storage and Writable Directories
PolyCMS separates publicly served media assets from private runtime artifacts across two RISE CRM root directories:
| Path | Visibility | Contents |
|---|---|---|
files/polycms/ |
Public (protected by .htaccess) |
Uploaded media files, thumbnails, and the fast permalink cache file files/polycms/.blog_prefix_cache.php. |
writable/polycms/cache/ |
Private | Frontend HTML page cache generated when Performance caching is enabled. |
writable/polycms/rate_limit/ |
Private | IP-based rate-limit counters for public forms and REST API v1 endpoints. |
writable/polycms/backups/ |
Private | Generated SQL backup archives (polycms_backup_YYYY-MM-DD_HH-ii.sql). |
writable/polycms/htmlpurifier/ |
Private | HTMLPurifier serialized definition cache for fast rich-text sanitization. |
CodeIgniter 4 Integration and Compatibility Bridge
To keep PolyCMS clean, maintainable, and fully isolated from other RISE CRM plugins (such as data_builder), its core architecture relies on three key layers:
- Base Controllers and Bootstrap 5 UI Bridge: All admin controllers extend
Base_admin_controller(which extends\App\Controllers\Security_Controller) and render inside RISE CRM's Bootstrap 5 layout viaViews/admin/rise_layout_bridge.phpandassets/css/admin/rise-bs5-compat.css. Public frontend pages and the REST API extendBase_public_controller(extending\App\Controllers\App_Controller). - CI3-to-CI4 Compatibility Layer:
polycms_rise_compat_helper.php,CI3_Instance_Compat.php,CI3_DB_Wrapper.php,CI3_Adapters.php, andPolycms_Base_Model.phpexpose collision-proofpolycms_*helpers (polycms_ci(),polycms_admin_url(),polycms_site_url(),polycms_get_option(),polycms_update_option(),polycms_staff_can(),polycms_set_alert(),polycms_redirect(),polycms_html_purify()) backed natively by CodeIgniter 4 services. - Lifecycle and Core RISE Hooks:
index.phpregistersregister_installation_hook,register_activation_hook,register_deactivation_hook,register_uninstallation_hook(preserves all tables), andregister_update_hook, plus RISE hooks for RBAC (app_hook_role_permissions_extension), staff/client sidebars (app_filter_staff_left_menu,app_filter_client_left_menu), scoped admin assets (app_hook_head_extension,app_hook_layout_main_view_extension), and stateless API CSRF exclusion (app_filter_app_csrf_exclude_urisforcms/api/v1.*+).
Database Schema (19 Dedicated Tables)
All PolyCMS tables are created from plugins/polycms/install/database.sql using InnoDB, utf8mb4_unicode_ci, and the active RISE CRM table prefix via $db->getPrefix() (default rise_, producing rise_blog_*):
| Functional Group | Tables ({prefix}blog_*) |
Count |
|---|---|---|
| Content | blog_posts, blog_pages, blog_page_meta |
3 |
| Taxonomy | blog_categories, blog_tags, blog_post_categories, blog_post_tags, blog_post_meta |
5 |
| Engagement | blog_comments |
1 |
| Media | blog_media |
1 |
| Navigation | blog_menus, blog_menu_items, blog_widgets |
3 |
| Extensions | blog_plugins, blog_plugin_options, blog_themes, blog_theme_options |
4 |
| Configuration | blog_settings, blog_permalink_settings |
2 |
PolyCMS never modifies core RISE CRM tables. It performs read-only lookups against RISE's users table (via App\Models\Users_model) for author names and avatars, and stores CMS options in {prefix}blog_settings with read-only fallback to RISE settings (app_title, date_format, time_format, timezone, language).
Routing and Request Lifecycle
Dynamic Routing Engine (config/Routes.php)
At bootstrap, index.php invokes polycms_register_routes() to register:
- Admin routes: Primary
/polycms/*routes alongside backwards-compatible/admin/polycms/*aliases. - REST API v1:
/cms/api/v1/{posts,pages,categories,tags,media}supportingGET,POST,PUT,PATCH,DELETE, andOPTIONSwithout CSRF token friction. - Root SEO routes:
/sitemap.xml,/sitemap_index.xml,/post-sitemap.xml,/page-sitemap.xml,/category-sitemap.xml,/sitemap.xsl, and/robots.txt. - Dynamic blog prefix routes: Loaded directly from
files/polycms/.blog_prefix_cache.phpwithout a database hit, including automatic301redirects from a previous prefix. - Safe CI4 404 Override:
$routes->set404Override(...)delegates unmatched URLs toFrontend::catch_all()to resolve root-level static pages or empty-prefix blog URLs, restoring HTTP404cleanly if no CMS entry matches.
Admin Request Flow
- CodeIgniter 4 routes
/polycms/*to a controller extendingBase_admin_controller. Security_Controllerauthenticates the RISE session and the controller checks granular role permissions (polycms_staff_can()).- The controller queries or updates data through a
Blog_*_modelusing the CI4 Query Builder. rise_layout_bridge.phpembeds the PolyCMS admin view cleanly inside RISE CRM's Bootstrap 5 shell with scoped TinyMCE, Select2, and SweetAlert2 assets.
Frontend Request Flow
config/Routes.phporset404Overridedispatches the request toFrontend.php(extendingBase_public_controller).polycms_frontend_initfires (allowing sub-plugins such as Maintenance Mode or XML Sitemap to intercept early).Frontend.phpchecks the HTML page cache (writable/polycms/cache/) if Performance caching is enabled, or resolves the post, page, category, tag, author, archive, or search query.Blog_theme_loaderloads the active theme from{prefix}blog_themesand walks the template hierarchy (single.php->category.php->tag.php->page.php->index.php).polycms_head, shortcodes (Blog_shortcode), widgets (Blog_widget), content filters, andpolycms_footerexecute to output the final HTML response.
Modular Extension Architecture
Sub-Plugin System
Blog_plugin_loader scans plugins/polycms/plugins/ for PHP plugin files containing standard docblock headers (Plugin Name:, Description:, Version:, Author:). Active sub-plugins recorded in {prefix}blog_plugins are booted during polycms_bootstrap_subplugins(), register hooks via polycms_add_action() and polycms_add_filter(), and can declaratively inject admin sidebar links via an optional menu.json file.
Theme, Widget, and Shortcode Systems
- Themes: Stored in
plugins/polycms/themes/with the bundledhead-randomBootstrap 5 theme active by default, supporting two widget areas (sidebarandfooter) and Theme Options. - Widgets: 9 built-in widget classes in
plugins/polycms/widgets/registered throughpolycms_register_widget(). - Shortcodes: 3 built-in handlers (
[polycms_post],[polycms_category],[polycms_tag]) inplugins/polycms/shortcodes/registered viapolycms_register_shortcode()and parsed viapolycms_do_shortcode().
Security Architecture
- Role-Based Access Control (RBAC): Every admin action enforces RISE role permissions (
polycms_view,polycms_create,polycms_edit,polycms_delete,polycms_settings). - XSS Sanitization: Rich-text HTML inputs are purified using the self-hosted
vendor/ezyang/htmlpurifierlibrary viapolycms_html_purify(). - SQL Injection Prevention: All database operations use parameterized CodeIgniter 4 Query Builder calls.
- Filesystem Protection:
polycms_validate_file_path()blocks directory traversal, andpolycms_secure_upload_directory()maintains.htaccessscript-execution guards insidefiles/polycms/. - Rate Limiting:
Polycms_Rate_Limiterenforces per-IP throttling on public comment submissions and REST API endpoints usingwritable/polycms/rate_limit/. - Direct Access Guards: PHP files validate execution context before running.
Related Documentation
- Hooks and Filters Complete Reference - Complete catalog of PolyCMS action and filter hooks.
- Template Tags and Helper Functions - Reference for theme and plugin helper APIs.
- Building a Custom Plugin - Step-by-step developer guide for creating PolyCMS sub-plugins.
- Building a Custom Theme - Guide to theme directory structure, headers, and template hierarchy.