# 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.

```text
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](../packages/catalog.md) 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](../frontend/index.md) 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

1. [Install guide](install.md)
2. [Admin docs](../admin/index.md)
3. [Frontend docs](../frontend/index.md)
4. [Creating Capell packages](../packages/README.md)

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