Acacia Laravel Package

Technical Evaluation

Architecture fit. Acacia is a code generator, not a runtime framework — its architectural value is that the generator is a stencil and every file it writes into app/ or resources/ becomes first-party code under our change control. That fits a Laravel monolith with an internal back-office surface (users, roles, moderation queues, ops lookups) and an existing spatie/laravel-permission install. It does not fit anything needing a design-system-accurate customer UI, an API-first backend, or multi-tenant isolation that isn't expressible in its publishable stubs. The architectural question to answer before adoption is which of the two front-end stories the package actually ships — the description advertises Vue 3 + Tailwind 3 via the jetstream-inertia-generator lineage, while other material describes Blade-rendered views. Inertia and Blade are different integration jobs with different Vite, alias, and Tailwind content-glob work. We must not estimate until a spike branch shows what the generator emits.

Integration feasibility. Feasible, cheaply, and only behind a compatibility gate. The package layers on top of Laravel conventions with publishable config, stubs, views, and migrations, which means the integration work is mostly review and adopt, not wire up. The gate: last release 2022-05-11 (v1.4.0) on a Laravel 9.2-era constraint, one effective maintainer, 43 stars, zero dependents. On Laravel 10/11 or PHP 8.3 we should assume it will not boot cleanly and budget a fork-and-patch task per Laravel major. The pre-install step is to diff the package's own composer.json constraints (php, laravel/framework, spatie/laravel-permission, Inertia/Vite) against our composer.lock — not the README.

Technical risk.

The risk framing for the portfolio: this is a scaffold to fork or vendor, never a platform bet. Low opportunity score and near-zero adoption signal make it a cheap trial, not a commitment.

Key questions.

1. Does it install and boot on our current PHP/Laravel, or does it already require a patch? (Answer in the spike, not in review.)
2. What does the generator actually emit — Blade or Inertia/Vue? This determines the estimate.
3. What is the real hours-to-first-working-CRUD number, measured against the ~2–4 hours a competent Laravel dev spends hand-building the same screen?
4. Who owns the fork, by name, and what is the documented exit path?
5. Is the admin panel explicitly not a differentiator in the roadmap narrative — so nobody tries to productize the scaffolded UI later?
6. Does the generated output survive deleting the composer dependency? It should: config, stubs, views, migrations, and generated resources all committed in-repo; only the generator command and service provider come from vendor/.

Integration Approach

Stack fit. Best fit: Laravel 9.2-era app, PHP 8.0/8.1, either Blade + Tailwind 3 or Inertia + Vue 3 matching the package's own lineage, spatie/laravel-permission already (or acceptably) present, and an internal-only admin surface. Poor fit: Laravel 11, Livewire-first codebases, design-system-driven customer UI, API-only backends. If we're on a newer framework, treat this as a fork-from-day-one decision, not a composer require.

Migration path. Two viable paths, and the PM should choose explicitly:

• Adopt-and-own (recommended if the spike passes). Spike branch → publish everything → commit published artifacts as the baseline → one resource end-to-end → decide. Every customization after that baseline is a diff we own.
• Fork-and-vendor (if the spike fails on framework version). Copy the generator and service provider into our repo, pin the behavior, and accept that we now maintain a small internal tool. This is more honest than editing composer.json constraints to force an install.

A third path is legitimate and should be priced alongside: a maintained admin framework (Filament, Nova, Backpack) across a 12–24 month horizon, weighed against Acacia's "generate once, own forever" model. Acacia is the middle option between build-from-scratch and buy-a-platform; price it against both ends.

Compatibility. Version-pin exactly ("savannabits/acacia": "1.4.0", not ^1.4) and record the pin in composer.json with a comment or runbook entry. Never patch vendor/ — publish or fork; a vendor patch is invisible to the next composer update and to teammates. Add the package's view/vendor paths to tailwind.config.js content by hand; missing globs are the classic prod-build break. Verify migration ordering against our existing users table before running — users/roles/permissions land there.

Sequencing.

1. Compatibility spike (time-boxed, 1–2 days). Branch, composer require --with-all-dependencies, php artisan list | grep -i acacia, publish, commit the artifacts. Deliverable: go/no-go plus the Blade-vs-Inertia answer.
2. Harden the seeder before the first migrate --seed anywhere non-local. Env-sourced credentials, firstOrCreate, hashed, environment-gated, empty ACACIA_ADMIN_EMAIL/ACACIA_ADMIN_PASSWORD in .env.example so it fails loudly. This is a day-one fix, not a hardening backlog item.
3. One boring resource end-to-end (name, status, a foreign key). Time-box a day, write down the hours. That number — not the README — is the adoption decision.
4. Stub hardening pass before scaling out: scoped search, paginate(25)->withQueryString(), policy/authorizeResource instead of inline can:, indexed default sort column. One afternoon on stubs beats hand-editing twenty controllers.
5. Scale out in ~30–60 minute loops per simple resource: generate → review diff → customize → add nav config entry → add policy + permission seeder entry → one feature test hitting index with a filter → commit as one reviewable unit.
6. Write the exit test into the runbook before the second resource, while intent is fresh.

Operational Impact

Maintenance. The honest framing: after adoption we maintain a forked scaffold, not a dependency. The recurring cost is (a) one fork-and-patch per Laravel major, (b) stub upkeep as our conventions evolve, and (c) the discipline of never regenerating over hand-edited files. Assign a named owner in the runbook — an unowned fork rots within two majors and then someone reconstructs intent from a diff. Mitigate the tail risk by committing every generated file and never .gitignore-ing the output: if the package vanished tomorrow, deleting the composer dependency should leave a working, if less convenient, app.

Support. No vendor SLA, no upstream to escalate to, one effective maintainer on a project last released in May 2022. Support = our own engineers plus the published artifacts in-repo. This is acceptable for internal tooling and unacceptable for anything with an external-facing uptime commitment. Debug order to put in the runbook: (1) route:list | grep acacia for existence and middleware; (2) publish output vs. committed resources; (3) Tailwind content globs; (4) permission:cache-reset; (5) composer show and PHP/Laravel versions.

Scaling. Scales fine along the axis it's designed for — number of admin screens — because each new module is a config line plus three generated files. It does not scale well along data volume: generated search and sort default to unindexed columns, so every resource needs a two-minute index review and composites for the columns actually filtered. Keep page sizes modest and ensure withQueryString() so filters survive pagination. Also scale-aware: the permission cache must be reset in the deploy script and in TestCase::setUp() if permissions are seeded in tests, or "admin can't see the menu after deploy" becomes a recurring false bug.

Failure modes. Ranked by likelihood × blast radius:

• Silent incompatibility — installs without erroring on a mismatched framework, then half the symptoms look like config bugs. Highest cost because it burns debugging time before the diagnosis lands.
• Privileged default account — the v1.4.0 seeder, ungated; security and compliance exposure, not an ops annoyance.
• Generator clobber — hand-edited controller overwritten on a dirty tree; recoverable only via prior commit.
• Prod-only styling break — Tailwind globs missing the vendor view path; passes dev, fails build.
• Index-screen timeout at volume — the package gets blamed for a schema decision.
• Abandoned fork — the slow failure; presents as "we can't upgrade Laravel" two years later.

Ramp-up. Low for any Laravel-competent engineer: the mental model is "generator is a stencil, output is mine," and the first resource is the whole tutorial. Realistic curve: ~1 day to first working generated CRUD (measured, not assumed), ~1 additional afternoon on stubs to reach the steady-state 30–60 minutes per simple resource. Non-engineering ramp-up matters too — the PM should set expectations that scaffolded screens are functional, not designed, and keep them off the customer path. Total pre-commitment investment before a go/no-go: two to three engineer-days. That is a cheap option on a back-office epic that would otherwise be sized in sprints — contingent, always, on the compatibility spike passing and the seeder being hardened before it runs anywhere but a laptop.