klytos-core-development

name

klytos-core-development

description

Guide for developing and maintaining Klytos CMS core. Use when modifying core files, adding MCP tools, fixing bugs, extending the core architecture, changing the build engine, modifying the installer, implementing hooks, or working with storage backends. Covers foundational principles (AI-first, privacy by design, security by default), architecture, boot sequence, manager pattern, MCP tool registration, and security checklist.

Klytos Core Development Guide

Foundational Principles

1. AI-First: MCP tools are the PRIMARY interface. Admin UI is secondary.
2. Privacy by Design: GDPR/RGPD compliant from line 1. No cookies, no tracking, no PII.
3. Security by Default: AES-256-GCM encryption, bcrypt passwords, CSRF, rate limiting.
4. Plugin Extensibility: Every feature must fire hooks so plugins can extend it.
5. Dual Storage: All code must work with both FileStorage AND DatabaseStorage.

Architecture

installer/
├── index.php              ← Front controller (routes all requests)
├── install.php            ← Multi-step installer
├── t.php                  ← Analytics tracking pixel
├── config/                ← Encrypted config files (.htaccess blocks)
├── core/                  ← PHP source (Klytos\Core namespace)
│   ├── app.php            ← Application bootstrap (singleton)
│   ├── storage-interface.php ← Storage abstraction
│   ├── file-storage.php   ← Flat-file storage implementation
│   ├── database-storage.php ← MySQL/MariaDB implementation
│   ├── hooks.php          ← Action/filter hook engine
│   ├── helpers-global.php ← klytos_*() global functions
│   ├── plugin-loader.php  ← Plugin discovery and loading
│   ├── page-manager.php   ← Page CRUD
│   ├── theme-manager.php  ← Theme configuration
│   ├── menu-manager.php   ← Navigation menus
│   ├── site-config.php    ← Global settings
│   ├── user-manager.php   ← Multi-user with roles
│   ├── task-manager.php   ← Review tasks/annotations
│   ├── version-manager.php ← Page version history
│   ├── block-manager.php  ← Modular HTML blocks
│   ├── page-template-manager.php ← Page template recipes
│   ├── analytics-manager.php ← Privacy-first analytics
│   ├── webhook-manager.php ← Event notifications
│   ├── cron-manager.php   ← Pseudo-cron scheduler
│   ├── audit-log.php      ← Action audit trail
│   ├── auth.php           ← Authentication (session, bearer, OAuth, app passwords)
│   ├── encryption.php     ← AES-256-GCM encryption
│   ├── build-engine.php   ← Static site generator
│   ├── helpers.php        ← Utility functions
│   ├── i18n.php           ← Internationalization
│   ├── license.php        ← Plugin license verification
│   ├── updater.php        ← OTA update system
│   ├── router.php         ← Request routing
│   ├── lang/              ← Translation files (en.json, es.json)
│   └── mcp/               ← MCP server implementation
│       ├── server.php     ← JSON-RPC 2.0 HTTP server
│       ├── tool-registry.php ← Tool registration and dispatch
│       ├── token-auth.php ← Multi-method auth (Bearer → OAuth → Basic)
│       ├── oauth-server.php ← OAuth 2.0/2.1 with PKCE
│       ├── rate-limiter.php ← Sliding window rate limiter
│       ├── json-rpc.php   ← JSON-RPC 2.0 parser/builder
│       └── tools/         ← MCP tool definitions
├── admin/                 ← Admin panel pages
│   ├── setup-wizard.php   ← Post-install setup wizard (2FA, AI keys, MCP)
├── plugins/               ← Plugin directory
├── public/                ← Static site output
├── data/                  ← Encrypted data storage
├── backups/               ← Backup archive storage
└── templates/             ← HTML templates

Boot Sequence (App::boot())

1. Register PSR-4 autoloader (CamelCase → kebab-case files).
2. Check installation status.
3. Initialize AES-256-GCM encryption.
4. Create storage backend (FileStorage or DatabaseStorage based on config).
5. Load main configuration.
6. Initialize i18n.
7. Initialize License manager (for plugin licenses only — core is free).
8. Initialize Auth.
9. Initialize all content managers.
10. Load Hooks engine + global helpers.
11. Load PluginLoader → discover and load active plugins.
12. Fire klytos.init action.

Installation & Setup Flow

1. Bootstrap (klytos-installer/installer.php): Downloads CMS from GitHub releases.
2. Installer (install.php): Simplified wizard — site name, username, password, dark/light preference, storage type. Sets setup_completed => false in config. Redirects to login after completion.
3. First Login: User logs in (always dark theme). bootstrap.php detects setup_completed === false and redirects to setup-wizard.php.
4. Setup Wizard (admin/setup-wizard.php): 5-screen guided setup:
   • Screen 1: 2FA (TOTP) setup (skippable)
   • Screen 2: Connection type (MCP / API Keys / Both)
   • Screen 3: AI provider API keys (conditional, skippable)
   • Screen 4: Application Password + MCP config (copy-paste ready)
   • Screen 5: Congratulations + AI prompt for site creation
5. Completion: Sets setup_completed => true. Existing/upgraded installs skip the wizard (key doesn't exist in config).

Adding a New MCP Tool to Core

1. Create file in core/mcp/tools/{feature}-tools.php.
2. Define a registerXxxTools(ToolRegistry $registry, App $app) function.
3. Use $registry->register(name, description, schema, handler, annotations).
4. Include the file in the MCP server's tool registration section.
5. Add the GPL-3.0-or-later license header.

Adding a New Manager

1. Create core/{feature}-manager.php in the Klytos\Core namespace.
2. Accept StorageInterface in the constructor (NEVER Storage or FileStorage).
3. Define a const COLLECTION = '{name}' for the storage collection.
4. Fire hooks at key points: {feature}.before_save, {feature}.after_save, etc.
5. Add it to App::boot() as a property with a getter.
6. Create corresponding MCP tools.
7. Add the GPL-3.0-or-later license header.

Storage Interface

All managers MUST use StorageInterface, never a concrete implementation:

// Collection + ID paradigm:
$this->storage->read('pages', 'about');           // Read
$this->storage->write('pages', 'about', $data);   // Write (upsert)
$this->storage->delete('pages', 'about');          // Delete
$this->storage->exists('pages', 'about');          // Check existence
$this->storage->list('pages', ['status' => 'published']); // List with filters
$this->storage->count('pages', ['status' => 'draft']);     // Count
$this->storage->search('pages', 'keyword', ['title']);     // Search
$this->storage->transaction(function($storage) { ... });   // Transaction

Fatal Error Handling

A register_shutdown_function in admin/bootstrap.php catches PHP fatal errors after boot:

• Catches E_ERROR | E_PARSE | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR
• Logs to PHP error_log() as fallback
• Logs to Klytos logs via Logger::writeAlways() (bypasses Developer Mode)
• Wrapped in try-catch so logger failures don't mask the original error

Logger::writeAlways() is the unconditional counterpart to Logger::write(). It skips Developer Mode and per-plugin checks. Use it only for fatal/critical errors that must always be recorded.

Security Checklist for Core Changes

• All user input sanitized (htmlspecialchars, Helpers::sanitizeHtml)
• SQL queries use prepared statements (DatabaseStorage handles this)
• No raw IPs stored (hash with Helpers or AnalyticsManager pattern)
• Hooks fired at key points (before/after save/delete)
• Errors logged, not exposed to users
• Fatal errors caught by shutdown handler (always logged)
• File permissions 0700 for directories, 0600 for keys
• CSRF tokens validated on all POST forms
• Rate limiting on public-facing endpoints
• GPL-3.0-or-later license header included

Coding Standards

• PHP 8.1+ with declare(strict_types=1).
• All code in English (comments, variable names, function names).
• Descriptive class/method/variable names.
• PHPDoc on every public method.
• Namespace: Klytos\Core (autoloaded via kebab-case filenames).
• License: GPL-3.0-or-later header on every file.
• Copyright: José Conti (https://plugins.joseconti.com — https://klytos.io).

SEO Requirements for Built Pages

Every page generated by the build engine MUST include:

• <meta name="generator" content="Klytos {version}">
• <meta name="description" content="...">
• Open Graph tags (og:title, og:description, og:image, og:url, og:type)
• Twitter Card tags
• Canonical URL
• hreflang tags (if multilingual)
• JSON-LD structured data (WebPage schema)
• Link to sitemap.xml in robots.txt
• llms.txt for AI crawler indexing

MANDATORY RULE: Translations

Every new translation key added to the core MUST exist in installer/core/lang/en.json. The en.json file is the master reference. If a key is added to es.json without adding it to en.json, the Translation Manager will not discover it.

Correct workflow:

1. Add the key in en.json (English).
2. Add the translation in es.json (and other languages if desired).
3. Use the key in code with __('namespace.key').