Awn Awn
Back to Awn
Documentation menu — Introduction
Start / Introduction
Version
1.0
Last verified
2026-08-09

Extend Awn without breaking Awn

Awn's extension system is a first-party, source-controlled API for adding presentation and optional tenant features. It is not a runtime marketplace: executable classes, routes, Blade views, CSS, and JavaScript must be deployed in the repository and allowlisted by an enum.

Continue with Architecture, then follow Build a theme or Build a plugin. Before release, use the release checklist.

Choose the correct boundary

Boundary Current location Responsibility
Product module Modules/{Admin,Charity,Core,Site} Permanent platform areas
Theme resources/views/themes/{slug} Public-site presentation
Plugin plugins/{Package} Optional behavior, data, routes, views, pages, and dashboard links
Catalog record themes, plugins Operational snapshot of deployed code
Tenant assignment organization_themes, organization_plugins One organization's selection and normalized settings

Themes do not own persistence or submissions. Plugins do not edit theme files. Optional extensions are never Laravel Modules.

Implemented catalog

  • Themes: najda, karam.
  • Plugins: contact-form, karam-banner, events, fundraising.
  • Slots: home_after_hero, page_after_content, before_footer.
  • Plugin pages: static and parameterized patterns such as events/{event}.
  • Dashboard contributions: zero, one, or many PluginDashboard values per enabled plugin.
  • Organization-home widgets: zero or more PluginDashboardWidget values through ContributesDashboardWidgets.
  • Super Admin contributions: optional global pages and widgets for installed/active plugins, independent of tenants and themes.
  • Global lifecycle: install, deactivate, reinstall, and destructive purge.
  • Per-organization lifecycle: compatible plugins can be enabled, configured, and disabled without deleting package data.

Handbook map

Start explains architecture, routing/tenancy, and terminology. Build covers themes, plugins, extension points, compatibility, and manifests. Reference records exact signatures, routes, configuration, cache keys, and current packages. Operate covers security, testing, troubleshooting, and release. Roadmap is future-only.

Non-negotiable rules

  • Register code through ThemeKey or PluginKey; a database value never chooses executable code.
  • Keep plugin models and migrations inside the package and apply BelongsToOrganization to tenant models.
  • Resolve tenant context before tenant queries.
  • Validate requests and normalize stored settings again before rendering.
  • Protect direct routes independently of navigation.
  • Cache portable arrays/scalars, not application objects.
  • Treat disable, global deactivation, and purge as different operations.
composer dump-autoload
php artisan awn:extensions:validate
php artisan route:list -v --name=plugin
php artisan test --compact
php artisan view:cache
npm run build

Events includes EventsSeeder.php; local/testing installation seeds one published example per organization under explicit tenant context and production installation skips sample data.

Fundraising is the complex reference package. It combines tenant migrations/models/policies, grouped organization navigation, dashboard widgets, project workflows, public plugin pages, private donation proofs, review attribution, supporters, and reports.

Choose surfaces independently: organization dashboard, Super Admin, and public/theme integration. Creating a plugin does not automatically require a menu, widget, or public page.