Capell Admin

capell-app/admin is the Filament panel package for Capell CMS. It adds the authenticated editor and operator surface for managing Core records, settings, package state, dashboards, permissions, and admin extension points.

Use this package when a Capell install needs a back-office UI. It depends on capell-app/core and should not be used to render public frontend output.

Package Boundary

Admin owns:

• the Filament panel plugin, resources, pages, dashboard Filament widgets, actions, form/table components, policies, and admin routes
• editor workflows for pages, sites, languages, layouts, themes, blueprints, media, redirects, users, roles, settings, package state, and upgrades
• admin extension points for contributed resources, pages, widgets, header tools, form schemas, table queries, relation managers, and validation hooks
• admin settings migrations and admin-specific cache commands

Admin does not own:

• shared content records and migrations; those are Core records
• public request handling or public HTML safety; that is Frontend and frontend add-ons
• marketplace account linking and catalogue install authorization; that is Marketplace
• migration/import execution; Admin can expose a recovery shell, but the recovery implementation is package-owned
• heavy import handlers; packages register visible import menu entries through ImportEntryRegistry and own the execution behind those entries

Install

Admin depends on capell-app/core and is optional. The recommended path is the installer (composer require capell-app/installer → php artisan capell:install), which adds Admin when you select it. To add it manually to an existing Capell app:

composer require capell-app/admin
php artisan capell:admin-install
php artisan capell:admin-setup

The full foundation installer may call Admin setup for you. On existing apps, use:

php artisan capell:admin-upgrade
php artisan capell:admin-clear-cache

The admin entrypoint is controlled by CAPELL_ADMIN_PATH; CAPELL_ADMIN_DOMAIN can move the panel to a dedicated host. Clear config cache after changing either value.

Runtime Surfaces

• Provider: Capell\Admin\Providers\AdminServiceProvider
• Config: config/capell-admin.php
• Entrypoint helper: Capell\Admin\Support\AdminPanelEntrypoint
• Routes: routes/web.php
• Main resources: ActivityResource, BlueprintResource, LanguageResource, LayoutResource, MediaResource, PageResource, PageUrlResource, RedirectResource, SiteResource, ThemeResource, UserResource
• Main pages: ExtensionsPage, SettingsPage, SiteHealthPage, SitemapPage, UpgradePage
• Main commands: capell:admin-install, capell:admin-setup, capell:admin-upgrade, capell:admin-clear-cache, capell:admin-cache-widgets, capell:admin-cache-configurators

ActivityResource includes a detail view that expands nested JSON changes into readable before-and-after rows for audit review.

Admin routes include a signed theme preview route and authenticated internal API routes under the configured admin path. Theme preview URLs are temporary admin URLs with signed middleware, site access checks, and no-store response headers; do not embed them into public output, cached HTML, or long-lived editor content.

Extension Points

Use the documented extension points instead of extending Filament resources directly:

Normal extension work should use the extenders and registries above. The advanced php artisan capell:admin-publish-resources [--type=<group>] [--resource=<label-or-class>] [--force] command publishes registered admin resources into the host application for direct customization. Published copies become host-maintained and can drift from package updates.

Data And Permissions

Admin operates mostly on Core models. Admin-owned persistence is limited to settings migrations and admin-specific operational state.

Policy and permission behavior must be registered globally, not only through a Filament resource. Marketplace contributes additional permission-aware surfaces when it is installed.

All editor-facing labels, notifications, and validation messages should use package translation files. Prefer Filament label method overrides over static label properties.

Verification

From the split repository root, with development dependencies installed, run Admin package tests after changing resources, policies, settings schemas, or panel registration:

vendor/bin/pest tests

For resource or schema changes, include the matching focused test file first. For UI behavior, verify the real Filament panel with a disposable admin account rather than stopping at the login screen.

Requirements And Support Policy

Each Capell 1.x minor receives security fixes for 24 months from its release date, and the latest 1.x minor is always supported. Upgrade all installed Capell foundation packages together to the same supported release before requesting a fix. See the Capell security policy for vulnerability reporting.

Support covers the dependency ranges above. When an upstream release reaches its own end of life earlier, upgrading that dependency may be required to receive a safe fix.

Troubleshooting

• Missing navigation usually means the resource/page contribution was not registered, a permission blocks it, or the package cache is stale.
• Missing fields in an editor form should be checked at the tagged extender and settings schema level before editing first-party resources.
• If Admin appears on the wrong host or path, check CAPELL_ADMIN_PATH, CAPELL_ADMIN_DOMAIN, and cached config.
• If theme preview stops working after an entrypoint change, regenerate preview links against the current admin host/path; signed URLs are host/path-sensitive.
• If cache commands do not affect newly added blocks or configurators, confirm the package registered its block/configurator classes and rerun the matching admin cache command.

Development

Package development and coordinated verification happen in the capell-app/capell monorepo. Split package repositories are release mirrors; use docs.capell.app for cross-package guidance. See the contribution guide, security policy, and licence.

Further Reading

The complete admin, extension, and troubleshooting guides are published at docs.capell.app.