Tomato Branches Laravel Package

Product Decisions This Supports

What this release tells you (v1.0.4): a patch-level bump from v1.0.3 with no described changes beyond a GitHub compare link. No new features, no deprecations, no breaking-change callouts. Treat this as routine maintenance and do not let it drive roadmap timing — but note that it confirms the package is still being touched.

Decisions the package is relevant to:

• Build vs. buy for "branch/location" data. tomato-branches is a TomatoPHP module that gives you a managed Branches entity (CRUD, relations, admin UI) inside a Laravel admin panel. If branch/location is a supporting entity rather than your differentiator, adopting the module beats a two-to-four-week build.
• Multi-location roadmap. Enables per-branch scoping of the things customers ask for first: users assigned to branches, branch-level reporting, branch-specific inventory/orders/appointments. This is the on-ramp to a "multi-branch" tier or a franchise/retail-chain segment.
• Feature sequencing. If the roadmap has "multi-branch" later, this package lets you ship a v1 of branch management now and defer the expensive part (tenancy isolation, per-branch permissions, hierarchy) until demand is proven.
• Scope negotiation. Because branch CRUD is cheap via the module, product can say no to bespoke branch work and spend the sprint on the flows that actually differentiate.

Constraint on all of the above: the evidence base here is one release title and a diff link. Before any of this informs a committed roadmap item, the team should read the actual v1.0.3→v1.0.4 diff and check the migration files. A patch release is not a maturity signal.

When to Consider This Package

Good fit when:

• You are already on the TomatoPHP / Laravel admin stack. The value is integration, not the CRUD itself — off-stack it is a small model + resource you would just write.
• You need a single-level branch list with the usual relations (branch → users, orders, inventory) and standard admin screens. Days, not weeks.
• You want a forkable starting point rather than a dependency. The surface area is small enough to vendor and own.
• The branch entity is infrastructure, not product surface.

Look elsewhere when:

• You need real multi-tenancy. Row-level branch_id scoping is not tenant isolation. For strict data separation, per-tenant databases, or tenant-aware queues/storage, use stancl/tenancy and build branches on top.
• You need hierarchical or geographic structure (region → district → branch, territory assignment, catchments). A flat branch table will get bent out of shape.
• Authorization is the hard part. Branch-scoped roles and approvals belong in spatie/laravel-permission with a team/branch scope, not in the module.
• You need versioning and release-note guarantees. Undocumented patch releases mean you should pin exact versions, read diffs before upgrading, and not rely on semver to signal breaking changes.
• The package is a hard dependency of your core domain. Prefer owning it.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, low-cost building block that gives the product a "branches / locations" capability — the thing customers ask for when they run more than one site. It lets us say yes to multi-location pilots without a custom build, and it is small enough that we are not locked in: if it stops fitting, we can replace it in a sprint. The latest version (1.0.4) is a maintenance patch with no behaviour changes, so there is no schedule or risk impact. Recommend we adopt it behind a proof-of-concept rather than as a platform commitment.

For engineering:

• Thin Laravel module in the TomatoPHP family: migrations, model, and Filament admin resources for a Branches entity. Low conceptual weight, conventional Eloquent — easy to read in an afternoon.
• Small blast radius and easily vendored/forked, so the exit cost is low. That is the main argument for trying it.
• Release hygiene caveat: v1.0.4 ships with no changelog text, only a compare link. Treat version numbers as advisory. Pin an exact version in composer.json, review the diff and any migrations before bumping, and cover the upgrade with an integration test.
• Do not let it become the tenancy layer. Use it for branch records and admin UI; put isolation and branch-scoped authorization in dedicated packages.

Recommendation: adopt for a bounded proof-of-concept (branch entity + branch-scoped user assignment), on the condition that the v1.0.4 diff is reviewed and the package is pinned. Re-assess once there is a release with actual notes or a documented breaking change.