Directory Structure

Pragma CMS utilizes a simple, clear, and secure architecture designed to isolate the core engine, individual sites, and publicly accessible assets. This "Clean Monolith" approach ensures stability and ease of updates.

cms-versions: Contains the core logic and services. Updates are applied strictly here. Do not modify this directory.
public: The only web-accessible directory. Contains index.php (site entry) which loads the corresponding site into the /sites folder and admin-platform.php (global management) which loads the CMS platform. Also contains assets that can be accessed via the web.
scripts: Contains utility scripts that can be run via the command line (CLI) or through scheduled tasks (Cron), such as automatically checking for updates or installing the server.
sites: Multi-tenant directory. Each subdirectory is an isolated site with its own templates, assets, and configuration, including database settings and a file defining the CMS version in use.
storage: Centralized storage for temporary files, logs, and application cache.

info

Shared vs VPS Hosting

The .htaccess file at the root is used on shared hosting (cPanel, OVH, etc.) as a routing layer that redirects all requests to /public. This ensures a clean entry point when you cannot control the server configuration. On VPS setups (Nginx, Caddy, or dedicated Apache), this file is not needed. The server is configured to point directly to /public, providing better security and performance.

config_master_key.php: Generated automatically on the first call to encrypt_secret(). This file contains the master encryption key used for securing sensitive data. It is critical to system integrity and must never be exposed or modified manually.
license.php: Contains the CMS license key generated by the platform. It defines the activation and validity of the installation and should remain protected from public access or modification.

Each section below provides details of these files and their purpose.

The Core: cms-versions

TEXT

/cms-versions
└── /[version]                         # The core engine version
    ├── /admin                         # Backend Administration & CRUDs
    │   ├── /content-types             # Content schema management
    │   ├── /database                  # Database inspection/management tools
    │   ├── /entries                   # Content entries management
    │   ├── /extensions                # Plugin/Extension manager
    │   ├── /includes                  # Core admin UI (header.php, navbar_left.php)
    │   ├── /languages                 # Localization manager
    │   ├── /media                     # Asset/Media library manager
    │   ├── /menus                     # Navigation builder
    │   ├── /messages                  # Form submissions & internal messaging
    │   ├── /pages                     # Static page manager
    │   ├── /redirections              # 301/302 Redirect rules manager
    │   ├── /routes                    # Custom routing interface
    │   ├── /settings                  # Global config (account/, general.php, seo.php, updates.php)
    │   ├── /taxonomies                # Category and tag management
    │   ├── /themes                    # Theme manager (index.php, editor.php)
    │   ├── /tools                     # Utilities (help.php, system_health.php, backup.php)
    │   ├── /users                     # User & Role management
    │   ├── dashboard.php              # Admin control panel entry
    │   └── login.php                  # Admin authentication interface
    │
    ├── /admin-platform                # Super-Admin Multi-Site Platform
    │   ├── /includes                  # Platform UI (header.php, footer.php, navbar_left.php, error.php)
    │   ├── /sites                     # Multi-site CRUD (index.php, create.php, update.php, delete.php)
    │   ├── /settings                  # Global platform config (updates.php, account.php)
    │   ├── /tools                     # Platform utilities (system_health.php)
    │   ├── config.php                 # Platform configuration
    │   ├── dashboard.php              # Platform overview
    │   ├── login.php                  # Platform auth
    │   ├── logout.php                 # Platform session termination
    │   ├── reset_password.php         # Platform password recovery
    │   ├── robots.php                 # Platform indexing rules
    │   └── router.php                 # Platform routing logic
    │
    ├── /api                           # Headless Endpoints
    │   ├── /content
    │   │   ├── index.php              # Main headless API entry point
    │   │   └── search.php             # API search queries
    │   ├── entries.php                # Entries endpoints
    │   ├── media.php                  # Media endpoints
    │   ├── menu_items.php             # Navigation endpoints
    │   ├── pages.php                  # Page endpoints
    │   ├── routes.php                 # Routing endpoints
    │   ├── forms.php                  # Form submission endpoints
    │   ├── taxonomies_terms.php       # Tag/Category specific endpoints
    │   ├── taxonomies.php             # Taxonomy structure endpoints
    │   └── templates.php              # Template endpoints
    │
    ├── /assets                        # Core CSS/JS Vendors
    │   ├── /vendors                   # Third-party libraries (editorjs, monaco, sortablejs, summernote)
    │   ├── /logo                      # Default CMS branding
    │   ├── /js                        # Core Javascript
    │   ├── /images                    # Core UI images
    │   ├── /icons                     # Core SVG icons
    │   ├── /fonts                     # Core typography
    │   └── /css                       # Core stylesheets
    │
    ├── /database                      # Migrations & Schema Engine
    │   ├── /backups                   # Core-level SQL dumps
    │   ├── /migrations                # Version-to-version DB migrations
    │   └── /schemas                   # Base SQL schemas
    │
    ├── /install                       # Installation Wizard
    │   ├── /assets                    # Installer styling/scripts
    │   ├── install.php                # Main installer execution
    │   └── readme.md                  # Installation instructions
    │
    ├── /lang                          # Core Translations
    │   ├── en.php                     # English dictionary
    │   └── fr.php                     # French dictionary
    │
    ├── /libraries                     # External Dependencies (No Composer)
    │   ├── /HTMLPurifier              # XSS protection
    │   ├── /PHPMailer                 # SMTP email sending
    │   ├── /sodium_compat             # Cryptography polyfill
    │   └── /Twig                      # Templating engine
    │
    ├── /pages                         # Core Controllers (Fallback UI)
    │   ├── /account                   # User UI (dashboard.php, profile.php, settings.php)
    │   ├── /auth                      # Auth UI (login.php, logout.php, register.php, reset_password.php)
    │   ├── list.php                   # Generic list view (articles, products)
    │   ├── single.php                 # Generic single view (article, product)
    │   ├── page.php                   # Static content & builder parsing
    │   ├── form.php                   # POST handler & fallback form rendering
    │   │                              # Note: Prefer FormManager::renderForm() in Twig/Builder to avoid '/form' in URLs.
    │   ├── home.php                   # Fallback homepage
    │   ├── maintenance.php            # 503 Service Unavailable screen (allows logged-in admins)
    │   ├── search.php                 # Global search engine controller
    │   ├── preview.php                # Content previewer (Admin only)
    │   ├── robots.php                 # Dynamic robots.txt generator (protects /admin, points to sitemap)
    │   ├── sitemap.php                # Dynamic XML index generator (handles multi-lang & >50k pagination)
    │   ├── account.php                # Account router fallback
    │   ├── feed.php                   # RSS/Atom feed generator
    │   ├── taxonomy_term.php          # Taxonomy term view
    │   ├── taxonomy_terms.php         # Taxonomy terms list view
    │   └── readme.md                  # Pages documentation
    │
    ├── /site-skeleton                 # Boilerplate for new site generation via Platform
    │   ├── /structure
    │   │   ├── /extensions            # Default extensions
    │   │   │   └── /starter-kit       # Example extension architecture
    │   │   │       ├── /classes       # Extension specific classes
    │   │   │       ├── /modules       # Sub-modules structure (api, crud, database, lang, pages)
    │   │   │       ├── /resources     # Assets, content-types, templates, themes
    │   │   │       ├── config.php     # Extension config
    │   │   │       ├── functions.php  # Extension logic
    │   │   │       ├── hooks.php      # CMS event hooks integration
    │   │   │       ├── install.php    # Extension setup
    │   │   │       ├── uninstall.php  # Extension teardown
    │   │   │       ├── manifest.json  # Meta data
    │   │   │       └── readme.md      # Extension docs
    │   │   ├── /content-types         # Site schema structures (collections, singles, structures)
    │   │   ├── /pages                 # Site static pages (account/, home.php, readme.md)
    │   │   ├── /assets                # Site static files (css, fonts, icons, images, js, logo, vendors)
    │   │   ├── /media                 # Site media processing (source/, images/, documents/, videos/)
    │   │   ├── /uploads               # User uploads handling (documents/, images/, videos/, upload.php)
    │   │   ├── /database              # Site specific DB backups
    │   │   ├── /storage               # Site ephemeral data (backups/, cache/, logs/, tmp/)
    │   │   ├── /templates             # Site fallback templates (emails/)
    │   │   ├── /themes                # Site themes (default-theme/, starter-kit/)
    │   │   ├── /lang                  # Site translations (en.php)
    │   │   └── config_db.php          # Empty site database connection boilerplate
    │   │
    ├── /storage                       # Core Ephemeral Data
    │   ├── /cache                     # Core caching
    │   ├── /tmp                       # Core temporary files
    │   └── /versions                  # Update tracking
    │
    ├── /system                        # The Engine (Classes & Bootstrap)
    │   ├── /classes                   # Core Object-Oriented Logic
    │   │   ├── AssetManager.php       # Handles static asset versioning/delivery
    │   │   ├── Database.php           # PDO Wrapper
    │   │   ├── TemplateEngine.php     # Twig wrapper & custom filters
    │   │   └── ...                    # (See full list: RouteManager, TaxonomyManager, etc.)
    │   ├── /enums                     # Enumerations (Hook.php, Section.php)
    │   ├── /templates                 # Core Base Templates
    │   │   ├── /account               # User account templates (dashboard, profile, settings)
    │   │   ├── /auth                  # Authentication templates (login, register, reset password)
    │   │   ├── /components            # Reusable UI components
    │   │   ├── /emails                # System emails (auto_reply, notifications, password reset)
    │   │   ├── /taxonomy              # Core taxonomy templates (listing & single views)
    │   │   ├── base.php               # Master HTML skeleton for generated pages
    │   │   ├── error.php              # Global error template
    │   │   ├── home.php               # Global homepage template
    │   │   └── page.php               # Global page template
    │   ├── bootstrap.php              # Global bootstrapper (paths, autoloader, dependencies)
    │   ├── config.php                 # App configuration logic
    │   ├── functions.php              # Global helper functions
    │   ├── hooks.php                  # Event listener registration
    │   ├── router.php                 # Request mapping logic
    │   └── version.php                # Version constant definition

Web Entry Point: public

TEXT

/public                                # The ONLY web-accessible directory.
├── .htaccess                          # Apache fallback routing to index.php
├── check-domain.php                   # Pre-flight check for Caddy to verify domain exists in DB before SSL generation
├── /assets                            # Publicly served static files
│   ├── /cms-versions                  
│   │   └── /[version]                 # Core CMS static assets (css, js, fonts, icons, logo, vendors)
│   └── serve-site-assets.php          # Secure asset router. Serves assets from non-public /sites/ dir upon validation.
├── admin-platform.php                 # Super-admin entry point (Multi-site management)
└── index.php                          # Single Entry Point for all HTTP requests. 
                                       # Resolves domain -> loads specific /site -> boots CMS.

Scripts & Utilities: scripts

TEXT

/scripts                               # Located outside public root to prevent HTTP access
├── /cron                              # Automated tasks
│   ├── check_updates.php              # Pings update server every 12h
│   └── backup.sh                      # Automated backup execution (added manually or via setup)
├── /cli                               # Command Line Tools
│   ├── clear_logs.sh                  # Flushes global and site-specific logs
│   └── deploy_staging.sh              # Clones production environment to staging
└── /setup                             # Infrastructure provisioning
    └── install_server.sh              # Provisions VPS (PHP, MariaDB, Caddy, Firewall, Scripts)

The Application: sites

TEXT

/sites                                 # Sandboxed multi-site configurations
├── /platform                          # The master CMS management platform
│   ├── config_db.php                  # MasterConfig class with MYSQL constants for master database
│   ├── cms_version.php                # Pins the platform to a specific CMS version
│   └── /media                         # Platform-level media (uploaded via Settings)
│
└── /[site-1]                          # Individual site instance directory
    ├── config_db.php                  # Site-specific database credentials
    ├── cms_version.php                # Site-specific CMS version pin
    ├── /extensions                    # Site-specific plugins (architecture identical to site-skeleton)
    ├── /content-types                 # Site-specific database schemas & structure configurations
    ├── /pages                         # Site-specific physical page templates (account/, home.php)
    ├── /api                           # Site-specific API endpoints
    ├── /assets                        # Site-specific CSS/JS/Fonts/Images
    ├── /media                         # Uploaded site media (source, images, documents, videos)
    ├── /uploads                       # Upload handling endpoint logic
    ├── /database                      # Site-specific SQL dumps/backups
    ├── /storage                       # Site-specific ephemeral data
    │   ├── /backups                   # Temporary backup storage
    │   ├── /cache                     # Routing and Twig cache
    │   ├── /logs                      # php-error.log and application.log (via logError())
    │   └── /tmp                       # Temporary processing files
    ├── /templates                     # Fallback Twig templates (emails/)
    ├── /themes                        # Site Themes (default-theme, starter-kit)
    └── /lang                          # Site-specific dictionary overrides (en.php)

System State & Cache: storage

TEXT

/storage                               # Global State & Persistence
├── /logs                              # Global logs
│   └── php-error.log                  # Auto-generated global error tracking
├── /tmp                               # Global temporary storage (e.g., handling update ZIPs)
└── /cache                             # Global caching (Domain mapping resolution, etc.)

Root Security & Configuration

.htaccess (Apache Routing Fallback)

info

Important Note

This file acts purely as a routing fallback to redirect traffic to the /public folder on shared hosting environments where the document root cannot be modified. If using the recommended VPS setup (Caddy, Nginx), this file is technically ignored, which is optimal for security. Do not delete it, as it ensures application portability.

Root PHP Files

TEXT

/
├── config_master_key.php              # Auto-generated secret key for cryptographic functions 
│                                      # (get_master_key(), encrypt_secret(), decrypt_secret()).
│
└── license.php                        # Auto-generated platform license key. Used to authenticate
                                       # Core updates, Site updates, and commercial Extensions.