From d0214eb2fdd4d16eb7fafa388a4e76268326fdcb Mon Sep 17 00:00:00 2001 From: Funky Waddle Date: Mon, 9 Mar 2026 00:07:44 -0500 Subject: [PATCH] Initialize CMS with finalized Notes and Specs --- NOTES.md | 60 ++++++++++++++++++++++++++++++++++++++++++ SPECS.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 NOTES.md create mode 100644 SPECS.md diff --git a/NOTES.md b/NOTES.md new file mode 100644 index 0000000..d6e1259 --- /dev/null +++ b/NOTES.md @@ -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. \ No newline at end of file diff --git a/SPECS.md b/SPECS.md new file mode 100644 index 0000000..e611e08 --- /dev/null +++ b/SPECS.md @@ -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 `` tag. + - `js('path', $attributes)`: Outputs a `