Tomato Branches Module Laravel Package

Technical Evaluation

Architecture fit

• The package is a module, not a standalone library. It assumes a host application already running tomatophp/tomato-admin, Filament v3, and the nwidart/laravel-modules loader. Fit is therefore binary: if we are on the TomatoPHP admin stack, it slots in as a first-class admin surface; if we are on vanilla Laravel, it is effectively unsupported.
• Functionally it delivers the conventional shape we would otherwise spec ourselves: a Branch entity (name, address, active flag), user↔branch association, Eloquent global scopes/helpers to filter records by branch, publishable migrations/seeders/config, and Filament resources for CRUD plus branch switching.
• It solves branch as a scoping dimension, not multi-tenancy. There is no evidence of per-tenant databases, strict row-level isolation guarantees, or hierarchical org structures. Products needing those should not treat this as a substitute.

Integration feasibility

• Low-effort path exists and is documented: composer require, php artisan migrate, confirm with module:list, publish config/lang, seed two or three branches, attach a user, then apply the branch scope to our own models.
• The real engineering work is on our side, not the package's: adding branch_id to our tables via our own add_branch_id_to_* migrations, and deciding branch resolution semantics (session → user default → first active branch) in a small CurrentBranch service so queued jobs and console commands can override explicitly.
• Two decisions must be made before any code lands: belongsTo (one branch per user) vs belongsToMany (pivot table), and whether branch doubles as the Spatie permission team_id. Both are cheap now and expensive to retrofit later.

Technical risk

• Adoption signal is weak. Zero stars, zero dependents, last release March 2024, and v1.0.1 ships with no changelog body — only a compare link. That is not evidence of instability, but it is also not evidence of maturity, test coverage, or an active maintainer.
• Ecosystem lock-in. Value is contingent on staying inside TomatoPHP + Filament. A Filament major-version bump, or TomatoPHP's own direction change, converts this from a dependency into a migration project. The documented failure mode (blank resource pages, Class not found on form components) is a silent-version-mismatch symptom, not an obvious error.
• Enablement fragility. "Installed but invisible" is called out as the top failure mode — modules are toggled in config/tomato.php / modules_statuses.json, and cached config makes it look broken. This is operational noise, not architectural risk, but it will consume support time.
• Package-owned migrations and published files. Shipped migrations must not be edited; published config/lang live in our tree and get overwritten on re-publish. Discipline is required, and we should assume we may eventually vendor-fork the module if we need deep changes.

Key questions

1. Are we committed to TomatoPHP/Filament v3 for this product's admin surface, or is that decision still open?
2. Do our users map to one branch or many, and does branch need to align with Spatie teams/permissions?
3. Does the product need strict tenant isolation (separate databases, contractual data separation), or is branch a filtering/reporting dimension?
4. What is the acceptable support posture for a zero-dependent, single-ecosystem package — do we need a maintained fork with a named internal owner?
5. What does the v1.0.0→v1.0.1 diff actually contain, and is there any test suite we can run in CI?

Integration Approach

Stack fit

• Only viable if the host app already runs tomatophp/tomato-admin, Filament v3, and nwidart/laravel-modules. Confirm this in writing before committing — installing into a bare Laravel app is explicitly not the supported path.
• If we use the shipped panel, the Filament resource auto-registers. If we run our own PanelProvider or split panels by module, we must register the plugin/resource explicitly rather than relying on discovery.

Migration path

• Treat the package as the source of the entity and admin CRUD, and take ownership of the scoping layer. Our own migrations add branch_id to domain tables; our own trait/global scope (BelongsToBranch) enforces filtering; the package's Branch model is consumed, not modified.
• Backfill needs a default branch: create a "Main"/default branch first, backfill existing rows to it, then enable the global scope. Enabling the scope before backfill is the classic outage.
• Do not edit vendor PHP or shipped migrations. Extend via config, model events/observers, and resource subclassing (extends the module's resource, or its modifyFormSchema() / modifyTableColumns() hooks) so composer update does not erase our work.

Compatibility

• Pin filament/filament and the module together in composer.json; treat them as a coupled pair across upgrades. TomatoPHP v4 targets Filament v3; older 3.x module lines target Filament v2.
• Stay inside ^1.0. v1.0.1 is a patch with no documented schema, route, or resource changes — a routine composer update should require no data migration or config republish.
• Baseline diagnostics for any "it's not working" ticket: php artisan about, php artisan module:list, check the panel's plugin/resource list, php artisan route:list | grep branch, and config:clear && cache:clear.

Sequencing

1. Time-boxed spike (3–5 days). Install into a disposable branch of a real app, seed branches, attach users, scope one real model, and document what breaks. Confirm the v1.0.0→v1.0.1 diff and whether tests exist.
2. Decisions locked. User↔branch cardinality, branch-vs-team permission model, branch resolution precedence, default-branch backfill plan.
3. Scoping foundation. Our migrations, CurrentBranch service, trait/global scope, BranchSeeder in the app (not the package) — merged before any feature consumes branch.
4. Pilot surface. One high-value, low-blast-radius feature (e.g., orders or reports filtered by branch) to prove the pattern end to end.
5. Broaden. Roll the scope trait across remaining models; wire branch switching into the panel; add branch-level authorization.
6. Contingency. If the spike fails on tenancy or permissions, fall back to building a minimal Branch model in-house — the schema is simple and the CRUD is not the expensive part.

Operational Impact

Maintenance

• Low ongoing cost if we only consume the package and confine customisation to config, observers, and subclassed resources.
• Medium cost if we diverge: published config/lang files must be re-diffed and re-published deliberately after minor bumps, and any vendor edit is a guaranteed upgrade break.
• Assign a named owner. With zero dependents and a single-maintainer ecosystem package, "someone on the team watches this" is the difference between a dependency and a landmine.

Support

• No commercial support, no SLA, no documented test suite. Internal triage capability must be assumed, not borrowed.
• Budget for a recurring "why is the Branches screen missing" class of ticket — almost always an enablement flag or cached config, rarely code.
• Keep the debugging checklist in runbook form; it resolves the majority of first-line issues without engineering time.

Scaling

• Scales to the flat company → branches → users/records model the package describes. Additional branches are rows, not architecture.
• Two scaling ceilings: (a) it is not multi-tenancy — do not promise contractual data isolation on top of it; (b) global-scope filtering applied naively across high-volume tables needs index coverage on branch_id, and cross-branch reporting will require explicit scope-removal queries rather than expecting the ORM to do it.
• Cross-branch analytics and consolidated roll-ups are out of scope for the package and should be planned as our own reporting work.

Failure modes

• Silent invisibility: module installed but not enabled, or config cached — no error, no screen. Highest-probability operational issue.
• Version skew: Filament/TomatoPHP mismatch produces blank resource pages or form-component Class not found.
• Scope leakage: branch filter not applied on a new model or a queued job, exposing another branch's data. Mitigate with a default-deny trait plus tests that assert cross-branch access fails.
• Backfill gap: global scope enabled before existing rows have a branch_id, silently hiding legacy records — the worst outcome, because it looks like data loss.
• Upgrade erosion: composer update overwrites a vendor edit or a published file that was edited in place.

Ramp-up

• A Laravel developer familiar with Filament can be productive in this package in about a day; the entity and resource are conventional.
• The non-obvious learning is the scoping discipline — where branch is resolved, how jobs override it, and which models are enrolled — which is our design, not the package's. Document it once, in the repo, with an asserted test.
• Recommended gate to adoption: the spike passes on a real model, the v1.0.1 diff is understood, and we have a written fallback to an in-house Branch model. If any of those is missing, do not proceed — the package accelerates a flat branch model, but it is not a foundation to build a tenancy story on.