Initialize CMS with finalized Notes and Specs
This commit is contained in:
commit
d0214eb2fd
60
NOTES.md
Normal file
60
NOTES.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
# The main SiteWeaver codebase
|
||||
|
||||
## Git repo
|
||||
- Repo: git@repos.qualitycoder.net:SiteWeaverCMS/cms.git
|
||||
- Default Branch: master
|
||||
|
||||
## Core Requirements
|
||||
- PHP 8.2
|
||||
- SQLite3
|
||||
|
||||
## Functionality
|
||||
- Blog Posts (via official plugin)
|
||||
- Pages (Add Page to Navigation checkbox on forms)
|
||||
- Admin Section (Auth, toggle for plugin activation)
|
||||
- Themes
|
||||
- Live in `themes/` directory
|
||||
- Metadata via `theme.md`
|
||||
- Blade wrapper, child themes, ZIP upload via marketplace
|
||||
- Note: Themes should not make DB changes on install
|
||||
- Page Builder Core
|
||||
- Media Manager
|
||||
- Focal Point Selector: Picking focus ensures art direction
|
||||
- Just-In-Time (JIT) Generation: URL parameters like `?w=800&fit=focal&fp-x=0.5`
|
||||
- Preview Cache Warming + Automated Cache Warming on Publish
|
||||
- Orphaned Media Watcher: Periodic cleanup of unreferenced images and JIT caches
|
||||
- Storage Abstractions: Support for Local Disk, S3, Nextcloud, and GCP
|
||||
- User Management
|
||||
- Roles: Admin, Editor, Author, User
|
||||
- Granular Permissions: CRUD-level control (View, Edit, Delete) per resource
|
||||
- Primary Admin Protection: Admin account cannot be edited or deleted
|
||||
- Author-specific post restrictions: Authors view/edit only their own posts by default
|
||||
- Search (Full-text, Category-based filtering, Faceted Search for Blogs)
|
||||
- API Support (RESTful, Sanctum)
|
||||
- Comments System (Spam protection, Approval workflow)
|
||||
- Navigation System
|
||||
- **Navigation API** allows plugins to add menu elements
|
||||
- **Backend Admin Navigation** config page for link management
|
||||
- Performance (Full-Page Caching, Image Optimization)
|
||||
- Security (2FA, Security Audits)
|
||||
- Backups (Database & Files accessible via Admin and `sw site:backup`)
|
||||
- Settings (Site Title/Description, SEO, Configurable Blog "Home" segment)
|
||||
|
||||
## Architectural Decisions
|
||||
- **Controller Pattern**: Use Laravel **Invokable Controllers** (Single Action Controllers) exclusively for all routing logic **within the CMS Core**.
|
||||
- **Identity Provider**: CMS Authentication is exposed via a `SiteWeaverAuth` middleware (`sw:auth`).
|
||||
- **Plugin System Interface**:
|
||||
- Plugins are **Laravel Service Providers** stored in `plugins/`.
|
||||
- Can register routes, navigation items, and add frontend features.
|
||||
- **File System**: Leverages Laravel's Flysystem for Local/Cloud abstractions.
|
||||
- **Frontend Interactivity**: Svelte components bundled via **Vite**.
|
||||
- **Block Editor Structure**: **JSON-First Storage** (a flat, order-sensitive array of block objects with `type` and `data` properties).
|
||||
- **Recommendation**: Implement **Server-Side Hydration (SSH)** for rendering. The Svelte editor outputs JSON on save. The PHP core then "hydrates" this JSON by matching block types to their respective Blade components to generate the "Cached Rendered HTML." If the cached version is missing or outdated, the core re-hydrates the JSON on-the-fly as a fallback.
|
||||
- **Plugin Migration Strategy**: Plugins can specify a path to their migration files within their Service Provider. If no path is specified, the Core defaults to scanning `/plugins/{plugin-name}/migrations/`.
|
||||
- **Site Routing & Reserved Slugs**:
|
||||
- **Default Admin Segment**: `/loom` (configurable via `.env` or settings).
|
||||
- **Priority**: System routes (Admin, API, Auth) always take precedence over dynamic Page slugs.
|
||||
- **Reserved Slugs**: `loom`, `admin`, `api`, `login`, `logout`, `register`, `sw-admin`, `dashboard`.
|
||||
- **Multi-Tenancy**: Architecture allows for future expansion.
|
||||
- **Unified Vite Build Pipeline**: Shared pipeline for Core and Official Plugins.
|
||||
- **Asset Conflict Management**: Each Plugin/Theme uses custom root-level CSS class (e.g., `.blog`) for styles and JS.
|
||||
80
SPECS.md
Normal file
80
SPECS.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
# 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.
|
||||
Loading…
Reference in a new issue