# What is Capell?

[![Latest Version on Packagist](https://img.shields.io/packagist/v/capell-app/capell.svg?style=flat-square)](https://packagist.org/packages/capell-app/capell)
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/capell-app/capell/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/capell-app/capell/actions?query=workflow%3Arun-tests+branch%3Amain)
[![Total Downloads](https://img.shields.io/packagist/dt/capell-app/capell.svg?style=flat-square)](https://packagist.org/packages/capell-app/capell)
[![Documentation](https://img.shields.io/badge/docs-docs.capell.app-blue?style=flat-square)](https://docs.capell.app)

Capell is a package-based CMS foundation for Laravel teams building structured websites. It provides the core content model, a Filament admin surface, public frontend rendering, and package-safe extension points without forcing every product feature into one application.

This repository is the 4.x host monorepo for Capell core packages.

![Capell admin dashboard](images/admin-dashboard.png)

## What This Repository Contains

| Package     | Composer name            | Package docs                                              | Practical job                                                                            |
| ----------- | ------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Core        | `capell-app/core`        | [Core docs](packages/core/docs/overview.md)               | Sites, pages, languages, page URLs, settings, package registry, install and upgrade flow |
| Admin       | `capell-app/admin`       | [Admin docs](packages/admin/docs/overview.md)             | Filament resources, dashboards, settings UI, users, media UI, and admin extension points |
| Frontend    | `capell-app/frontend`    | [Frontend docs](packages/frontend/docs/overview.md)       | Public request resolution, cache-aware page rendering, and frontend extension points     |
| Installer   | `capell-app/installer`   | [Installer docs](packages/installer/docs/overview.md)     | Browser installer guide and installer cleanup flow                                       |
| Marketplace | `capell-app/marketplace` | [Marketplace docs](packages/marketplace/docs/overview.md) | Extension marketplace browsing, acquisition, and package install authorization records   |

The umbrella package is `capell-app/capell`. Package-specific READMEs cover the lower-level shape of each host package:

- [Core package](packages/core/README.md)
- [Admin package](packages/admin/README.md)
- [Frontend package](packages/frontend/README.md)
- [Installer package](packages/installer/README.md)
- [Marketplace package](packages/marketplace/README.md)

## Start Here

Choose the path that matches what you are doing:

| I want to...                        | Read this first                                              |
| ----------------------------------- | ------------------------------------------------------------ |
| Try Capell in a fresh Laravel app   | [Quickstart](getting-started/quickstart.md)             |
| Install Capell into a real app      | [Install guide](getting-started/install.md)             |
| See interactive content delivery    | [Capell Interactions](getting-started/capell-interactions.md) |
| Understand the package architecture | [How Capell works](getting-started/how-capell-works.md) |
| Work in this monorepo               | [Development docs](development/index.md)                |
| Build or maintain an add-on package | [Package authoring docs](packages/README.md)            |
| Operate an installed site           | [Operations docs](operations/index.md)                  |
| Check the package catalogue         | [Approved packages](packages/catalog.md)                |

The full documentation map lives at [docs/README.md](README.md).

## Quick Local Demo

For a disposable local trial:

```bash
composer create-project laravel/laravel music-store
cd music-store
composer require capell-app/capell -W
php artisan filament:install --panels
php artisan capell:install --demo --url=http://localhost:8000
php -S 127.0.0.1:8000 -t public public/index.php
```

Open `http://localhost:8000/admin` for the admin panel and `http://localhost:8000` for the frontend. The quickstart includes database setup, queue notes, screenshots, and first-run fixes.

## Core Ideas

Capell gives a Laravel app the foundations most CMS builds end up recreating:

- structured page trees and localized page URLs
- multi-site and multi-language records
- a Filament admin surface for content, settings, media, users, and package screens
- a frontend request pipeline with cache-aware rendering
- interaction triggers that can lazy-load widgets and Layout Builder fragments
- package-driven extension points for admin, frontend, settings, migrations, assets, and operations

The normal content path is:

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

Writes should go through Actions, and structured boundary state should use Data objects. This keeps domain rules out of Filament resources, Livewire components, controllers, and frontend templates.

## Main Extension Points

- `CapellCore::registerPageType(...)`
- `CapellAdmin::contributeToAdminSurface(...)`
- `CapellAdmin::registerAdminBridge(...)`
- `SettingsSchemaRegistry::register(...)`
- `CapellAdmin::registerDashboardWidget(...)`
- `CapellAdmin::registerWidget(...)`
- tagged admin extenders such as `PageSchemaExtender::TAG`
- `RenderHookRegistry::register(...)`
- `WidgetRegistry::register(...)`
- `CacheInvalidationRegistry::registerDependency(...)`

Add-on packages should use these surfaces rather than patching host package classes.

## Documentation Structure

| Section                                               | Audience                                            |
| ----------------------------------------------------- | --------------------------------------------------- |
| [Getting started](getting-started/quickstart.md) | Developers evaluating or installing Capell          |
| [Admin](admin/index.md)                          | Developers working with the Filament admin surface  |
| [Frontend](frontend/index.md)                    | Developers working with public rendering            |
| [Packages](packages/README.md)                   | Package authors and maintainers                     |
| [Performance](performance/README.md)             | Developers tuning caches, assets, and rendering     |
| [Operations](operations/index.md)                | Operators handling deploys, upgrades, and incidents |
| [Reference](reference/index.md)                  | Lookup material, glossary, ERDs, and credits        |

Historical implementation plans and internal review notes do not belong in the public docs tree.

## Development Commands

This repository uses Composer scripts for the common maintenance loop:

| Command                  | Purpose                                                                     |
| ------------------------ | --------------------------------------------------------------------------- |
| `composer prepare`       | Discover Testbench packages                                                 |
| `composer test`          | Run the Pest test suite                                                     |
| `composer test:fast`     | Run the sharded fast Pest command                                           |
| `composer lint`          | Run changed-file Pint formatting                                            |
| `composer analyze`       | Run the fast PHPStan configuration                                          |
| `composer preflight`     | Run PHPStan and changed-file formatting                                     |
| `composer preflight:all` | Run Composer path checks, Rector, Pint, Prettier, ESLint, PHPStan, and Pest |
| `composer serve`         | Build and serve the Testbench workbench at localhost                        |

For local package path setup and matching branch guidance, see [Development](development/index.md).