How Capell Works

Capell is built as a package-based CMS foundation for Laravel. The host packages in this repository own the main schema, admin surface, frontend surface, and plugin lifecycle support, while larger features ship as optional add-on packages.

The Core Model

Most Capell work follows this path:

Site -> Page -> Layout and content fields -> Rendered frontend page

A site represents a public web property. A site can have one domain or several, one language or several, and its own pages, settings, and theme choices.

A page is a structured record in a hierarchy. Pages own translated URLs, type-specific fields, publishing state, media relationships, and layout relationships.

A layout connects content to frontend rendering. A blueprint shapes how content is edited, rendered, and reused across pages, widgets, layouts, and package-owned content models.

The main content records are deliberately small and composable:

Model	Practical job
`Site`	Owns domains, languages, settings, pages, and theme choices
`Language`	Defines locale and default-language behaviour for a site
`Page`	Stores the page tree, publishing state, page type, and relationships
`PageUrl`	Stores localized URLs and slugs for each page
`Blueprint`	Stores reusable editing, rendering, and behaviour rules
`Layout`	Connects structured content to frontend templates
`Theme`	Records the active theme path and identity
`Media`	Stores media library records and relationships
`Translation`	Stores translated field values across models

Pages use a nested tree, so moving a parent page can affect child URLs, navigation, breadcrumbs, cache keys, and frontend rendering. That is why writes should go through Capell actions instead of model methods with hidden side effects.

Request And Editing Flow

Capell keeps the editing surface, domain behaviour, and frontend rendering separate.

Admin form or HTTP request
    -> Data object
    -> Action::run()
    -> Core model write
    -> Events, subscribers, and cache invalidation
    -> Frontend request resolves the updated page

Data objects carry structured state across package, HTTP, Livewire, and Filament boundaries. Actions own the domain behaviour. Filament resources, Livewire components, controllers, and commands should call actions rather than duplicating CMS rules inline.

On the public side, frontend requests resolve the site, language, page, layout, and render context before returning a Blade response. When caching is enabled, the frontend middleware can serve cached HTML and rely on model events or registered cache dependencies to invalidate affected pages after content changes.

In-page editing sits outside that rendered HTML. Frontend Authoring waits until the page has loaded, calls the beacon, and only then decorates the page for an authenticated admin. Anonymous users and non-admin users get the same ordinary page HTML: no editor scripts, no hidden region markers, no model IDs, and no signed edit URLs.

Host Packages

These packages make up the normal product in this repository:

Package	Composer name	Status	What it owns
Core	`capell-app/core`	`Available`	Main schema, models, registries, settings orchestration, install and upgrade flow
Admin	`capell-app/admin`	`Available`	Filament admin surface, resources, settings UI, dashboards, and admin extension points
Frontend	`capell-app/frontend`	`Available`	Public routing, rendering, cache-aware middleware, asset aggregation, and frontend extension points
Installer	`capell-app/installer`	`Available`	Installer guidance and cleanup flow
Marketplace	`capell-app/marketplace`	`Available`	Extension marketplace browsing, acquisition, and install authorization support

Optional Packages

Optional packages extend the host surfaces rather than replacing them.

Examples:

Capell Foundation: blog, navigation, redirects, default theme, frontend authoring, HTML minify
Capell Publishing Pro: publishing-studio and preview tooling
Capell Operations: backup, recovery execution, diagnostics, authentication log
Capell Search & SEO: SEO operations and site search

Use Approved packages for the package registry.

Service Provider Responsibilities

Each host package boots a different part of the platform.

Provider	Responsibility
Core service provider	Registers migrations, config, morph map requirements, commands, policies, translation listeners, and shared macros
Admin service provider	Registers Filament resources, admin commands, schema extenders, event subscribers, type interceptors, and Filament macros
Frontend service provider	Registers public routes, frontend middleware, Livewire components, HTML caching, minification, navigation helpers, and frontend assets

Add-on packages should plug into these surfaces through registries, tagged services, contracts, and service providers. They should not patch host package classes directly.

What Editors See

Editors mainly work through the Admin package:

pages and page URLs
sites and languages
layouts, themes, and media
settings, dashboards, and package-backed screens

Some screens only appear when the relevant optional package is installed. Admin should describe those as Optional, not built-in.

What Frontend Owns

Frontend resolves the request, identifies the site and page, builds the render context, and returns the response. When caching is enabled, it also participates in static HTML cache reads, writes, invalidation, and related middleware.

See Frontend for the operational flow.

Extension Points

Capell is meant to be extended through package-safe hooks.

Need	Extension point
Register a page type	`CapellCore::registerPageType()` with `PageTypeData`
Register package admin concerns	`AdminBridge` and `AdminBridgeRegistrar`
Add admin pages or resources	`CapellAdmin::contributeToAdminSurface(...)`
Add dashboard widgets	`CapellAdmin::registerDashboardWidget()`
Add settings UI	`SettingsSchemaRegistry::register()` and `registerSettingsClass()`
Add admin widgets	`CapellAdmin::registerWidget()` or `registerDiscoverableWidgets()`
Add frontend widgets	`WidgetRegistry::register()`
Add frontend HTML	`RenderHookRegistry::register()`
Add Tailwind sources or imports	`TailwindAssetsRegistry::registerSource()` and `registerImport()`
Wire cache invalidation	`CacheInvalidationRegistry::registerDependency()`

Practical Reading Order

Blueprints affect editor fields, frontend components, widgets, layouts, cache behavior, and reuse. Use package extension points instead of editing host models directly.