PolyCMS
Back to Main Site

PolyCMS Architecture Overview

Last updated on May 21, 2026 00:09

PolyCMS is engineered as a highly extensible, modular Content Management System built on Laravel 12 and Vue 3. It bridges the gap between traditional monolithic CMS platforms (like WordPress) and modern Headless solutions by offering a Hybrid Open Core architecture.

1. High-Level Stack

  • Backend Foundation: PHP 8.3+, Laravel 12, PostgreSQL (Primary) / MySQL.

  • Frontend Admin SPA: TypeScript, Vue 3 (Composition API), Vite 7, TailwindCSS 3.2, Pinia.

  • API Layers: RESTful API (/api/v1) via Sanctum and a GraphQL endpoint via Nuwave/Lighthouse.

  • Editor: TipTap-based Block Editor (JSON storage with Server-Side HTML rendering).

2. Directory & Layer Separation

PolyCMS enforces strict separation of concerns, moving away from "fat controllers" to a robust Service and Action-oriented architecture.

app/
├── Actions/        # Single-responsibility execution classes (e.g., CreatePost, ProcessRefund)
├── GraphQL/        # Schema-first resolvers, Queries, and Mutations
├── Http/
│   ├── Api/V1/     # REST Controllers handling HTTP Request/Response cycles
│   └── Frontend/   # Controllers for standard Blade template rendering
├── Models/         # Eloquent ORM definitions
├── Services/       # Core Domain logic (OrderManager, HookManager, MediaService)
└── Providers/      # Core bootstrapping

3. The Core Extensibility Engines

The power of PolyCMS lies in its ability to be extended without altering the core codebase.

A. The Hook & Filter System (HookManager)

Inspired by WordPress but implemented with modern PHP, the Hook facade allows modules to intercept execution via Actions (void callbacks) and Filters (value transformers).

  • Actions: E.g., Hook::addAction('order.refund.succeeded', [RefundLog::class, 'handle'])

  • Filters: E.g., Hook::addFilter('content.render.html', fn($html) => sanitize($html))

B. Dual-Model Architecture: Native vs Sandbox

PolyCMS isolates risk by categorizing modules into two operational modes defined in module.json:

  • Trusted Native Modules:

Have full access to the PHP core, filesystem, and database. Booted natively via Service Providers. Use these for deep SEO optimization, caching, or core overriding.

  • Sandbox Remote Apps:

Execute out-of-band with zero-trust policies. They interact purely through the REST/GraphQL APIs via an Admin-approved Sanctum App Token. Use these for CRM syncs, Mailchimp integrations, or AI processing.

C. The Multi-Theme Engine

Unlike standard Laravel applications, PolyCMS supports concurrent Theme Activation:

  • Main Theme: Provides the global app.blade.php layout and base assets.

  • Sub Themes: Provide specialized block templates (e.g., a landing page template) that can be assigned to individual Posts or Products, overriding the Main Theme locally while inheriting global CSS.

4. Admin SPA State Management

The PolyCMS Admin Panel is a Single Page Application (SPA). Data flow follows a strict pattern:

  • Routing: vue-router intercepts the URL and loads the specific View component.

  • State: Global UI states (Dark Mode, Active Dialogs, Notifications) are managed by Pinia stores.

  • API Communication: Components utilize Axios interceptors to inject Sanctum Bearer tokens automatically.

  • Validation: A centralized validation composable (useValidation) powers standard Form components (FormField, FormInput) with dynamic client/server error mapping.

Next Steps

To begin extending the core, review the Module Development Lifecycle or explore the Hooks & Filters Reference to see available extension points.