Architecture

Deep Dive • VoltCMS 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().

.htaccess → index.php → bootstrap.php → App::run() → Router::resolve() → AdminApp or PublicApp

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 Database using prepared statements and {p} table prefixes. Content paths, visibility flags, tags, menus, redirects, and the search_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 via ContentStore). Uploaded media lives under uploads/YYYY/MM/{random}.{ext}, and custom code assets live under assets/{css,js}/{id}-{name}.{ext} (mode 0644 so 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 to user/backups/revisions/{content_id}/{revision_id}.html. Purging deletes the DB row first and moves files to user/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.

6. SEO, Syndication, Settings & Defense in Depth

VoltCMS centralizes cross-cutting behavior so rules never drift across features:

  • Centralised SEO & Syndication: Seo computes indexability, canonical overrides, and fallbacks in one place. Syndication powers robots.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 (returning 503 if no site URL is set).
  • Media, Thumbnails & Autocomplete: Uploads are checked with finfo against an allowlist (no SVGs, and user/uploads/.htaccess blocks script execution), while Thumbnailer generates 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 configures Format. When maintenance_mode is strictly 1, non-admin routes return 503 with Retry-After without starting sessions for ordinary visitors unless a cmssid cookie 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 (only connect-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 via Migrator across .sql and .php migrations.
  • Quiet Logs by Default: Errors are written to user/logs and never exposed on screen unless debug is enabled in user/config/app.php.