# Extension Structure

Capell extensions are Laravel packages that add one focused capability through public Capell extension points. Keep extension code outside the core packages unless the feature belongs to the platform foundation.

Use this page as the routing guide before creating a package, adding a provider, or changing package docs.

## Choose the extension shape

| Need | Use | Start with |
| --- | --- | --- |
| Add a first-party optional feature | Add-on package in `capell-app/packages` | [How To Create A Capell Extension](https://docs.capell.app/packages/how-to-create-a-capell-extension/) |
| Add fields, actions, tools, pages, resources, or dashboard widgets to the admin | Admin extension points and tagged extenders | [Admin Extensions](https://docs.capell.app/packages/admin-extensions/) |
| Add frontend output, render hooks, theme assets, Blade components, Livewire components, or route behavior | Frontend extension points | [Frontend Extensions](https://docs.capell.app/packages/frontend-extensions/) |
| Add a package that ships migrations, settings, actions, routes, translations, and tests | Standard package anatomy | [Package Anatomy](https://docs.capell.app/packages/package-anatomy/) |
| Register a core CMS type, schema, event subscriber, render hook, or model binding | Core extension point | [Extending Capell](https://docs.capell.app/packages/core/extending-capell/) |

Prefer the narrowest extension point that owns the behavior. A tagged extender is usually safer than replacing a resource. A render hook is usually safer than overriding a theme view. Publishing core schemas should be the last option because published files stop receiving upstream changes.

## Package boundaries

An extension package should have one clear runtime shape:

- `shared` providers for package registration, config, translations, and container bindings used in more than one runtime.
- `admin` providers for Filament pages, resources, widgets, settings contributors, admin extenders, and Extensions page actions.
- `frontend` providers for render hooks, Blade components, Livewire components, routes, themes, and frontend assets.
- `console` providers for install commands, import/export commands, scheduled work, and developer tooling.

Declare the same boundary in `capell.json` through `contexts`, `requires`, and `providers`. Do not boot admin-only classes on frontend requests.

## Documentation for extensions

Every documented package should have:

- `README.md` as the package landing page.
- `capell.json` with `name`, `kind`, `capell-version`, `productGroup`, `tier`, `bundle`, `contexts`, `requires`, and provider metadata.
- `docs/**` for deeper install, admin, frontend, database, testing, or integration guides.
- Public screenshots or diagrams only when they help someone configure, extend, or verify the package.

The package shelf is generated from those files. If a package is missing or grouped incorrectly, fix `capell.json` before changing this docs site.

## Review checklist

- Business logic lives in Actions or services, not Filament resources or page classes.
- User-facing strings are translated by the package.
- Runtime providers match the manifest contexts.
- Destructive or data-changing behavior has direct Action tests.
- Admin/editor behavior is not leaked into public frontend output.
- Public docs explain install, configuration, extension points, and failure modes the package actually has.

[Package Authoring](https://docs.capell.app/core/package-authoring/)
  [Service Providers](https://docs.capell.app/packages/service-providers/)
  [Testing Packages](https://docs.capell.app/packages/testing-packages/)