The canonical complex plugin. Walked end-to-end.

Why this plugin is the canonical reference

Most plugins in production are small. A sending driver is one class plus a connection blade. A payment gateway is a service plus a redirect controller. A simple sidebar add-on is one Hook::add call. None of those exercise the whole plugin SDK — and small plugins are not the right reading exercise for an author trying to understand how big a plugin can responsibly grow.

acelle/ai exists at the other end of the spectrum. It is a self-contained AI subsystem: an agent chatbox, universal text-rewrite components, KB-grounded coach personas, and an admin observability dashboard. Activating the plugin in an Acelle install adds the entire AI surface without touching core code; deactivating removes it cleanly. The plugin uses every concept the rest of these docs cover, in production. Reading it is the fastest way to see how the patterns combine when the feature is non-trivial.

The file tree at a glance

From the plugin's own README:

None of those folders are bespoke. Every one maps directly to a section in the rest of these docs. Reading the plugin is a process of recognising the same pattern shipped at scale.

Eight Eloquent models — the audit substrate

The AI module's data layer is shaped around auditability: every conversation, every model invocation, every tool call, every user feedback, and every blob of raw provider output is captured for replay and observability. Eight models cover that substrate:

Three patterns from this list translate directly into other plugins. Splitting "raw provider responses" into a separate table from "rolled-up summary" lets the rollup table stay small enough to scan. Nullable FKs to customers and users let the same row work for authenticated and anonymous traffic. One-row-per-day rollups give the admin dashboard cheap reads without a heavy JOIN against the activity tables.

Fourteen migrations one-line each

The migration filenames in storage/app/plugins/acelle/ai/database/migrations/ tell their own story — additive over time, immediately reversible, never a destructive schema move:

Read the migrations top-to-bottom and you have the schema evolution of the entire AI module. Every additive migration is a feature ship — the additive shape is what makes the plugin's delete_plugin_* rollback always work, even when an admin uninstalls after a year of feature accretion.

Every hook the plugin uses

The plugin's ServiceProvider exercises every hook pattern except FILTER. A grep for Hook::* against storage/app/plugins/acelle/ai/src/ServiceProvider.php:

REGISTRY (Hook::add) — six contributions

• Nine add_translation_file entries at register() lines 175-197 — one per translation surface (rewrite, chatbox, prompts, wait, subject AB, settings, admin usage, audit, permissions). Each surface is a separately editable file in the admin Languages UI.
• layout.head.assets at boot() line 688 — contributes chatbox CSS + JS to every page that extends the master app / admin layouts.
• layout.body.before_close at boot() line 699 — contributes the chatbox bubble HTML and the sparkle popover before every page's </body>.
• admin.sidebar.groups at boot() line 718 — adds the AI group with its three or four child links to the admin sidebar.

All six gate themselves with aiPluginAvailable() — a helper that ultimately resolves to Plugin::getByName('acelle/ai')->isActive(). Returning null when the plugin is gated off is the conventional way to disappear cleanly without unloading the service provider.

EVENT (Hook::on) — two lifecycle listeners

• activate_plugin_acelle/ai at line 472 — runs artisan migrate against the plugin's migrations folder.
• delete_plugin_acelle/ai at line 546 — accepts the $keepData flag, rolls back migrations when not set, preserves the audit tables when set.

BEHAVIOR (Hook::set) — one icon URL override

• icon_url_acelle/ai at line 522 — overrides the per-plugin BEHAVIOR hook so the admin Plugins page renders the AI module's own icon instead of the host's default plugin.svg.

Together these are most of the plugin's hook surface. Reading ServiceProvider.php top-to-bottom is the fastest way to see how the patterns combine in production.

The chatbox UI surface

The plugin contributes three universal Blade components in resources/views/components/ — none of them require the host application to know they exist:

• <x-mc-ai-chatbox> — the floating chatbox bubble that opens into a multi-turn agent conversation. Mounted via the layout.body.before_close REGISTRY hook so it appears on every app + admin page.
• <x-mc-ai-rewrite> — universal "rewrite this text" affordance that can be dropped next to any textarea in the host. Plugin-namespaced, no central registration.
• <x-mc-ai-subject-ab-generator> — generates A/B subject-line variants from a prompt. Used in the campaign editor.

These three components show the pattern for "plugin contributes UI to multiple host pages without forking each page": ship the component as an anonymous Blade component under your plugin's view namespace, register it through the layout REGISTRY hooks for global mounting, or have host pages opt-in by including it directly. Both patterns work; the AI plugin uses both.

Nine files × eighteen locales

The plugin's register() registers nine separate translation files. The Language::dump() machinery then materialises each into seventeen non-English locale runtime folders under storage/app/data/plugins/acelle/ai/lang/. The result on disk: 153 runtime translation files (9 files × 17 non-English locales + 9 English originals = 162 minus the 9 English masters = 153 dump-clones), each separately editable through the host's Languages admin UI.

The nine surface files (registered via the $aiLangFiles loop in ServiceProvider::register()):

• ai_rewrite — the universal text rewrite component
• ai_chatbox — the chatbox UI
• ai_chatbox_prompts — pre-canned prompts shown in the chatbox
• ai_chatbox_wait — the smart-wait UI ("looking up… running tool… composing reply")
• ai_subject_ab — the subject A/B generator
• ai_settings — admin settings page labels
• admin_ai_usage — admin usage / cost dashboard
• admin_ai_audit — admin audit / replay UI
• admin_ai_permissions — admin per-feature permission toggles

This split is the practical answer to "how do I keep translation files small enough that a translator can edit one in a single sitting": one master per logical surface, registered separately, materialised per locale, edited independently through the admin UI.

Plugin-owned config files

The plugin owns two config files under config/ — registered in ServiceProvider::boot() via $this->mergeConfigFrom() and reachable through the standard config('ai.*') and config('ai-navigation-hints.*') helpers. Plugin-owned config is the right place for static metadata that does not change per-install (engine catalog, prompt templates, navigation defaults); admin-editable settings live in the ai_settings table seeded by migration.

The split — config for plugin-shipped immutable defaults, DB rows for admin-editable mutable settings — is a pattern that ports cleanly to other plugins. Putting both in the plugins.data JSON column is tempting but punishes admin UI performance; a dedicated indexed table was the right call.

The test infrastructure

The plugin's test directory follows the host's tests/ shape — Unit + Feature folders plus a PluginTestCase base class at the root:

storage/app/plugins/acelle/ai/tests/
├── PluginTestCase.php          ← seeds the plugin row as active before every test
├── Feature/
│   ├── AIHandler/              ← engines, agent loop, tools, observability writer
│   └── PluginLifecycle/        ← lifecycle integration tests
├── Unit/                       ← isolated unit tests (no Laravel boot for some)
├── Fixtures/                   ← test fixtures + factories
├── Snapshots/                  ← Pest snapshot artefacts
└── Support/                    ← test-only helpers

The host's phpunit.xml registers the plugin's testsuite as <testsuite name="Plugin: acelle/ai">. ./vendor/bin/pest --testsuite="Plugin: acelle/ai" runs the full suite in parallel with the host's own Unit + Feature suites.

The PluginTestCase at the root demonstrates the per-request gate-cache reset trap that every plugin shipping middleware should adopt — see the Testing § gate-cache trap for the full pattern. Without it, the second test in the suite onward observes stale cache state from the first test's boot.

How to learn from it

Reading every line of a hundred-thousand-token plugin is not the right exercise. A four-step recipe is more useful:

1. Clone or symlink the plugin into a host install. Activate it. Open the admin sidebar — the AI group should appear. Click "Settings" on the admin Plugins page entry — the plugin-landing dashboard should load. This proves the plugin's UI surface is wired into your local host.
2. Read src/ServiceProvider.php top-to-bottom. Forty minutes. Every concept covered in Plugin architecture + Hook system + UI injection + Translations appears in this one file at production scale. Cross-reference with the deep-dive pages as you go.
3. Trace one feature end-to-end. Pick the chatbox bubble. Find the entry point (layout.body.before_close hook in ServiceProvider), follow the partial it returns (ai::partials.body_assets), find the anonymous component that renders the bubble, find the JS that mounts it, find the API route the JS calls, find the controller, follow it down to the AIHandler runtime engine, watch the AIConversation + AIMessage + AIRequest rows get inserted. Two-to-three hours, end-to-end. After this you will know which patterns the AI plugin uses and which it does without.
4. Adapt one pattern to your own plugin. Pick the smallest one that maps — usually the per-translation-surface registration loop, or the admin sidebar group, or the per-day rollup-table approach. Strip out the AI-specific code; keep the structural pattern. That is the plugin author's day-one productivity gain.

Where to go next

This is the last of the eleven developer deep-dives. From here, the index hub is the natural recap: Documentation index shows every page in the cluster organised into Foundation / Building / Quality / Reference. The developer landing is the marketing-shaped entry point for new visitors arriving from search.

Two practical next steps when you are ready to ship a real plugin: the activate → test → delete cycle from the Testing deep-dive proves the plugin's delete_plugin_* hook listener cleans up correctly. Plugin architecture § Recovery from broken state is the page to bookmark for production runtime issues — three failure modes plus the exact fix path each.

Beyond AcelleMail-specific patterns, the broader Laravel ecosystem applies. Plugin code is vanilla Laravel; the host runtime loader is the only non-standard piece. Anything you know about Eloquent, Blade, Pest, queues, scheduling, or middleware works inside the plugin folder unchanged.