cms/NOTES.md

# 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`)
- Restore System (Restore from backup via Admin or `sw site:restore`)
- 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.
Initialize CMS with finalized Notes and Specs 2026-03-09 05:07:44 +00:00			`# 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`)
docs(cms): update specifications for SW_FILE helper and restore system - Renamed file() helper to sw_file() to avoid PHP conflict. - Added Restore System specification to CMS notes and specs. 2026-04-13 17:47:41 +00:00			- Restore System (Restore from backup via Admin or `sw site:restore`)
Initialize CMS with finalized Notes and Specs 2026-03-09 05:07:44 +00:00			`- 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.`
docs(cms): update specifications for SW_FILE helper and restore system - Renamed file() helper to sw_file() to avoid PHP conflict. - Added Restore System specification to CMS notes and specs. 2026-04-13 17:47:41 +00:00			- Asset Conflict Management: Each Plugin/Theme uses custom root-level CSS class (e.g., `.blog`) for styles and JS.