cms/SPECS.md

SiteWeaver CMS Core - Technical Specifications

This document defines the build-ready technical specifications for the SiteWeaver CMS Core (/cms).

1. System Requirements & Stack

• Framework: Laravel 11.x
• PHP Version: 8.2+
• Database: SQLite3
• Frontend Stack:
  • Admin CSS: Semantic UI
  • Admin/Editor JS: Svelte 5 (compiled via Vite)
• Asset Conflict Management: Each plugin/theme must utilize a custom root-level CSS class (e.g., .blog) to prevent global namespace pollution.

2. Core Routing & URL Management

2.1 Admin Segment

• Default: /loom (Branded segment)
• Configuration: Managed via ADMIN_PATH in the .env file.
• Priority: System routes (Admin, Auth, API) have absolute priority over dynamic page slugs.

2.2 Reserved Slugs

• loom, admin, api, login, logout, register, sw-admin, dashboard, themes, plugins, media.

3. Block Editor: Server-Side Hydration (SSH)

3.1 Data Schema (JSON-First)

Content is stored as a JSON array of block objects:

[
  { "type": "header", "data": { "level": 2, "text": "Hello SiteWeaver" } },
  { "type": "paragraph", "data": { "text": "This is a block-based CMS." } }
]

3.2 Rendering Flow

• On Save: The Svelte editor outputs JSON. The PHP core hydrates this JSON into a "Cached Rendered HTML" column in the database.
• On Request: The CMS serves the "Cached Rendered HTML" for high performance.
• Fallback: If the cached version is missing/outdated, the PHP core re-hydrates the JSON on-the-fly using Blade components associated with each block type.

4. Plugin & Theme Architecture

4.1 Plugin Lifecycle

• Discovery: CMS scans the /plugins directory for Service Providers.
• Activation: Toggle-based via Admin UI.
• Migrations:
  • Plugins can define a custom migration path in the Service Provider.
  • Default Path: /plugins/{plugin-name}/migrations/.

4.2 Theme Engine

• Location: /themes/{theme-name}/.
• Required Files: theme.md (metadata) and a root layout Blade file.
• Discovery: Automated scanning of the themes/ directory.
• Inheritance: Support for Child Themes (overriding parent files via directory hierarchy).
• Asset Discovery & Loading:
  • Helpers:
    • css('path', $attributes): Outputs a <link> tag.
    • js('path', $attributes): Outputs a <script> tag.
    • file('path', $attributes): Smart Asset Helper. Automatically detects file type (via extension/metadata) and outputs the appropriate HTML tag (<img> with srcset support, <video>, <audio>, or <a> for documents like PDF).
      • JIT Image Parameters: For images, special keys in the $attributes array like w, h, fit, q (quality), and fm (format) are automatically intercepted and passed to the JIT image generation engine.
  • Functionality: These helpers output the FULL HTML TAG.
  • Attributes: The optional $attributes array allows for specifying defer, async, media, id, class, alt, w, h, etc.
  • Recursive Search: The engine first looks in the current Theme folder. If a Child Theme is active and the file is missing, it automatically falls back to the Parent Theme folder.

5. Media Manager Specification

5.1 Storage & Logic

• Abstraction: Uses Laravel Flysystem (supports Local, S3, Nextcloud).
• Focal Point: Coordinates (X/Y) stored as metadata.
• JIT Generation: Managed via Glide/Intervention.
  • URL Format: /media/{filename}?w=800&fit=focal&fp-x=0.5&fp-y=0.5.

5.2 Performance

• Preview Cache Warming: Images generated during the author's preview phase.
• Automated Cache Warming: Background jobs generate responsive srcset sizes upon publication.
• Orphaned Media Watcher: Periodic task to prune unreferenced original files and JIT caches.

6. Authentication & Identity Provider

• Middleware: sw:auth middleware.
• Functionality: Protects non-CMS Laravel routes using the CMS's session, user roles, and 2FA.
• Roles: Admin (Protected), Editor, Author, User.

7. Performance & Security

• Full-Page Caching: Native public-route caching.
• Security Audits: Automated periodic auditing for activated plugins.
• Backups: sw site:backup and Admin-side trigger to snapshot the SQLite DB and project root.