81 lines
4.3 KiB
Markdown
81 lines
4.3 KiB
Markdown
|
# 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:
|
||
|
|
```json
|
||
|
|
[
|
||
|
|
{ "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.
|