Architecture
When I set out to build VoltCMS, I had one strict rule: zero bloat, maximum speed, and complete predictability. Instead of pulling in heavy frameworks or Composer dependencies, VoltCMS is engineered from scratch around a clean separation of replaceable core code and untouched user data. Below is an in-depth look at every layer of the system—from request routing and hybrid storage to theme safety nets, menus, and zero-downtime-style backups.
1. The Golden Rule: Core vs. User Data
One of the biggest headaches with traditional CMS platforms is keeping upgrades painless without risking your content or custom themes. VoltCMS solves this at the directory level by splitting the entire filesystem into two strictly isolated zones:
core/ (Replaceable Engine)
Houses the core engine classes (engine/), admin controllers (admin/), base theme, and database migrations (migrations/). Every class lives in the Cms namespace—one file per class, with zero Composer dependencies. Upgrading the CMS simply means uploading new core files while leaving user/ untouched.
user/ (Untouched Site Data)
Contains everything unique to your site: db.php, config/, content/, uploads/, themes/, backups/, cache/, and logs/. System updates never overwrite anything inside user/.
2. Request Lifecycle: Public vs. Admin Isolation
Speed comes from doing as little work as possible on public page loads. Every request enters through .htaccess and index.php, loads core/engine/bootstrap.php (autoloader and helpers), initializes App::run() and Env::init(), checks installation status, and resolves routes via Router::resolve().
On public requests, VoltCMS enforces a strict version gate (returning 503 if installed_version does not match CMS_VERSION) and keeps heavy admin classes out of memory. Admin-only classes like ContentWriter, ContentAdmin, AdminApp, and ThemeValidator are never loaded on public requests, except when ContentAdmin::preview() delegates to PublicApp.
Inside AdminApp, a prefix-to-controller map dispatches routes like /admin/content, themes, media, code, tags, and settings. Session handling, CSRF checks on every POST, authentication (requiring a session whose user row still exists on every route except sign-in), and the update gate run centrally for all admin controllers.
3. Hybrid Storage, Atomic Writes & Data Safety
Why choose between database query speed and flat-file simplicity when you can use both? VoltCMS pairs relational indexing with direct filesystem storage:
-
Indexed Metadata & Search in SQL: All SQL runs through
Databaseusing prepared statements and{p}table prefixes. Content paths, visibility flags, tags, menus, redirects, and thesearch_index(kept in sync inside the same save transaction) live in the database for fast querying. -
Sanitised HTML & Media on Disk: Post bodies are stored as sanitised HTML in
user/content/posts/{id}.html(read once per public page viaContentStore). Uploaded media lives underuploads/YYYY/MM/{random}.{ext}, and custom code assets live underassets/{css,js}/{id}-{name}.{ext}(mode0644so the web server serves them directly). -
Atomic Writes & Non-Destructive Archives: File replacements use
Files::writeAtomic()(temp file + rename). Before overwriting a content body, the old HTML is saved touser/backups/revisions/{content_id}/{revision_id}.html. Purging deletes the DB row first and moves files touser/backups/deleted/, while media and asset archives keep bounded history (such as the newest 10 code versions) and never auto-delete from disk. -
Strict Visibility Rules: Public pages must satisfy
status='published' AND visibility='public' AND deleted_at IS NULL. Private pages remain reachable only by URL plus password (or an admin session) and are excluded from every public listing.
4. URLs, Redirects, Menus & Homepage Control
Router evaluates fixed discovery routes first—/search, /feed.xml, /sitemap.xml, /robots.txt, /tag/{slug}, and /assets/base/...—so reserved slugs cannot be hijacked at the top level. Any remaining 1-to-12-segment path is routed to PublicApp::content().
Single-Source Paths & 301 Redirects
content.path is the single source of truth for content URLs. Renaming or moving a page triggers repath() inside the save transaction, updating descendants and recording redirects in content_redirects—while only redirecting to published, public items and 301-redirecting case mismatches to the canonical URL.
Configurable Homepage & Menus
The homepage can be driven by home_page_id via ContentRepository::publicHomeItem() (re-checked on every public request so private or trashed pages never leak at /), redirecting its own path to / with a 301. Menus support one level of sub-items, safe URLs (/path, http(s), mailto, tel), active/trail state calculation, and graceful empty fallback on menu errors.
5. Child Themes, Live Editor & Crash Recovery
Themes require no build step. PublicRenderer::render() locates templates and layout.php via Theme::locate()—checking the active child theme first and falling back to the base theme. Child theme assets are linked as /user/themes/{name}/assets/...?v={mtime}, while non-web-accessible base theme files are served via ThemeAssets at /assets/base/....
When editing theme files through ThemeFilesAdmin and ThemeFiles, every path is strictly confined to real directories under user/themes/{theme}/ (blocking symlinks, base, core/, configs, logs, and backups). Saves verify optimistic concurrency via SHA-1 hash comparison, run lint and manifest validation (ThemeCodeLint and ThemeValidator), archive a revision (keeping the newest 20), write atomically (0644), invalidate opcache, and log security metadata without ever logging file content.
Throwable or ParseError, PublicRenderer catches and logs it, re-rendering with the base theme—and if base itself fails, Theme::safeFallback() renders a minimal fallback page instead of crashing.
6. SEO, Syndication, Settings & Defense in Depth
VoltCMS centralizes cross-cutting behavior so rules never drift across features:
- Centralised SEO & Syndication:
Seocomputes indexability, canonical overrides, and fallbacks in one place.Syndicationpowersrobots.txt, batched sitemaps (up to 50,000 URLs with ETag conditional responses), and the top-20 RSS feed using the same public, non-noindex filter (returning503if no site URL is set). - Media, Thumbnails & Autocomplete: Uploads are checked with
finfoagainst an allowlist (no SVGs, anduser/uploads/.htaccessblocks script execution), whileThumbnailergenerates 400px GD thumbnails safely. Admin pickers use ARIA 1.2 comboboxes backed by debounced, non-cached JSON endpoints capped at 12 results. - Settings & Maintenance Mode:
App::settings()loads settings once per request with safe defaults and configuresFormat. Whenmaintenance_modeis strictly1, non-admin routes return503withRetry-Afterwithout starting sessions for ordinary visitors unless acmssidcookie is present.
- Strict CSP & Escaping: All output is escaped with
e(). Admin pages enforce a strict Content Security Policy with no inline scripts or styles (onlyconnect-src 'self'for admin lookups), while public pages use a per-request CSP nonce. - Cryptography & Migrations: Secrets like TOTP seeds are encrypted using a key derived from
app_key, and sensitive identifiers like IPs, usernames, and recovery codes are stored as keyed hashes. Schema and data changes run deterministically in order viaMigratoracross.sqland.phpmigrations. - Quiet Logs by Default: Errors are written to
user/logsand never exposed on screen unlessdebugis enabled inuser/config/app.php.