Tomato Branches Module Laravel Package

Product Decisions This Supports

• Feature bet: multi-location as a first-class dimension. This module makes "branch" a real entity (name, address, active status) with user assignment and query scoping, so decisions like "should orders/reports/users be branch-aware?" can be answered with a cheap yes instead of a quarter of custom work. Relevant to retail, franchise, service-area, clinic/studio chains, and B2B SaaS with regional teams.
• Build vs. buy (adopt vs. build). Take it when branches are supporting infrastructure, not the differentiator. The package supplies the CRUD, relations, migrations, and Filament admin screens; your team spends its budget on the branch-aware logic that actually creates value — pricing per location, inventory allocation, branch-level reporting, location-scoped permissions.
• Roadmap sequencing. It de-risks a common upgrade path: shipping single-location first with a clean branch_id and scoping trait in place, then turning on multi-location later without a schema rewrite. Approving it early is a hedge against rework, not just a feature.
• Scope containment on admin surface. Because it ships Filament resources and quick branch switching, internal-ops tooling for locations lands without a design/dev cycle. PM can promise "ops can manage branches themselves" on a much shorter timeline.
• Permissions model fork in the road. The package forces an explicit decision — one branch per user (belongsTo) vs. many (belongsToMany with a pivot), and whether branch maps onto Spatie's team_id. That decision is cheap now and expensive later; the module makes it a visible, dated choice rather than an accidental one.
• Vendor/stack commitment signal. Adoption implicitly commits you to the TomatoPHP + Filament ecosystem for admin surfaces. That is a platform decision as much as a feature decision, and should be reviewed as such.
• Release signal — weak. v1.0.1 is a patch with no changelog body beyond a compare link; nothing indicates new capability or a breaking change. Treat it as maintenance. 0 stars, 0 dependents, and a last release of March 2024 mean there is no adoption evidence to borrow — this is an unproven dependency, and the roadmap should carry a mitigation line item for that.

When to Consider This Package

Consider it when:

• The product is Laravel and the admin panel is already (or is about to be) TomatoPHP/Filament — installing into a bare Laravel app is explicitly unsupported.
• The branch model is flat: company → branches → users and records. You need CRUD, relations, scoping, and admin UI — not a hierarchy engine.
• You want a fast spike or an internal-ops capability, and can absorb the cost of forking or replacing the module later if it stalls.
• You are willing to own the parts the module does not: a CurrentBranch resolver, queue/console overrides, and your own add_branch_id_to_* migrations.

Look elsewhere when:

• You need true multi-tenancy — separate databases, hard tenant isolation, contractual data-separation guarantees. This is a scoping convenience, not a tenancy boundary; presenting it as one is a security and compliance risk.
• You need org hierarchies, regional rollups, or branch groups above the leaf level.
• You are outside the TomatoPHP stack, or your panel is split across multiple Filament PanelProviders where auto-discovery will not fire.
• You need vendor SLAs, security response commitments, or a maintained release cadence. Zero dependents and a year-plus since the last release mean you are effectively the maintainer of last resort.
• Your branch logic is the product (e.g., cross-branch transfer pricing, franchise royalty calculations) — heavy customization against a small package is worse than building the entity yourself.

Gate before committing: a time-boxed spike that pins Filament and the module together (v4 targets Filament v3; 3.x lines target v2 — mismatches surface as blank pages or Class not found), confirms the module enables cleanly via modules_statuses.json + config clear, and walks one real branch-aware query end to end. Read the v1.0.0→v1.0.1 diff and check test coverage — sparse notes mean validation happens in the spike, not in the version number.

How to Pitch It (Stakeholders)

For executives: This is an open-source Laravel module that gives us branch/location management — the entity, the user assignments, the query scoping, and the admin screens — instead of us building it. It shortens time-to-market for multi-location features and lets engineering spend its time on the branch-aware logic customers pay for. Cost to try is low if we are already on the TomatoPHP/Filament stack; cost to adopt is a platform commitment to that ecosystem for our admin surfaces. Two honest caveats: the package has no visible adoption (zero dependent projects, zero stars) and no release since March 2024, so we would be an early adopter carrying maintenance risk. Recommendation: fund a short, time-boxed spike with a defined exit criteria, and treat "adopt" as conditional on it passing — not as a decision made today.

For engineering: Use it as a head start, not a foundation you cannot leave. The value is the Branch model, the migrations, and the Filament resource schema — copy the patterns into your own resources where sensible. Do not edit shipped migrations or vendor PHP; add your own add_branch_id_to_* migrations and extend or subclass the resource so composer update stays clean. Pin filament/filament and the module together and verify the version line before install. Put branch resolution behind a CurrentBranch singleton (session → user default → first active branch) so queued jobs and console commands can override it explicitly — that is the piece most likely to bite you in production. Top failure mode is "installed but invisible": check php artisan about, module:list, the panel's plugin registration, and route:list | grep branch before assuming a code problem. Known risks: ecosystem lock-in, unclear long-term maintenance, and whether the user↔branch cardinality and any Spatie team_id overlap match our permissions model — settle that before the first migration, because retrofitting team scoping is painful.