Filament Subtenant Scope Laravel Package

Product Decisions This Supports

• Feature-level: "second-level scoping" for an existing Filament admin. If your product already has one tenant (company, account, org) and users keep asking for a working context inside it — "just the North branch", "just my region", "just this department" — this package is a ready-made answer that touches zero resource code. That makes it a candidate for a small roadmap item rather than a multi-sprint initiative.
• Build vs. buy at the right layer. Rebuilding the equivalent (topbar selector, request-scoped resolver, URL → session → user-storage persistence chain, panel-aware Eloquent global scope, nav badge and global-search propagation) is roughly 1–3 weeks of Filament-fluent engineering plus ongoing maintenance. Adoption is a 1–3 day spike. The buy case is strong if the semantics fit; the cost of being wrong is low because it's MIT and easily forked.
• The core product fork: "filter" vs. "boundary". This package is a presentation-layer working context, not an isolation mechanism. It does not enforce permissions, does not prevent cross-scope access at the data layer, and no-ops outside the registered panel. Deciding which of those two things your customers are actually asking for is the real decision this package forces — and it should be made explicitly, in writing, before anyone installs it.
• Use cases it plausibly serves: franchise/multi-location ops dashboards, field-service dispatch by service area, clinic or dealership groups by location, regional sales managers reviewing their patch, support teams triaging by department. All staff-facing, all "soft filter", all with a manageable FK shape (service_area_id, region_id).
• Workflow/product surface decisions: shareable scoped URLs (?scope_service_area=12) mean support can hand a colleague a link to exactly the view they were discussing; session-plus-user persistence means the context survives logout. Those are UX commitments you can make in a spec and ship cheaply.
• Adoption sequencing decision. Because opting one resource into a model registers a global scope on the whole model, you cannot pilot this on a single screen. The product decision is "which models are in scope," not "which pages." Plan the cutover by data domain, not by feature.

When to Consider This Package

Adopt when:

• You are already on Filament v4/v5, PHP 8.2+, Livewire v3/v4 — no stack change required.
• The sub-scope is genuinely a convenience or working context: reducing noise for staff, not restricting access for tenants.
• You have a clean FK (service_area_id) on most target models, or a small number of custom join cases you're willing to write as scopeSubTenant{Key} methods.
• One to three scopes is enough. The package stacks scopes, but every added dimension multiplies the test matrix and the "why is my data missing?" support load.
• The consumers are internal/staff users who can be trusted with a soft filter, and the compliance/contractual story doesn't hinge on it.
• You can pin the version and accept a young, single-maintainer dependency with a fork escape hatch. Budget a regression suite around the global scope — that's where bugs will hurt.

Look elsewhere when:

• You need hard isolation: per-tenant databases, row-level security, or anything an auditor would call a control boundary. This is the wrong layer for that, and shipping it as if it were is a product risk, not a technical one.
• You need the same scoping in API endpoints, queued jobs, scheduled reports, or exports. The global scope is panel-aware and deliberately no-ops outside the panel — so the UI and your background jobs will disagree on totals. Any KPI that must reconcile between the dashboard and the nightly report needs a separate design.
• You're not on Filament. There's no Livewire/Blade/Inertia/React-admin path here.
• You need hierarchical or permission-derived scope trees, per-scope roles, or an audit trail of who viewed which scope.
• You need a single-option experience to still filter. The README is explicit: with exactly one accessible option the selector renders as a static label and applies no filter. That's defensible UX, but it is a semantic surprise worth verifying against your expectations before it becomes a bug report.
• Your team can't absorb vendor risk on a 30-star, zero-dependent, v1.x package — in which case budget the fork or the rebuild instead.

How to Pitch It (Stakeholders)

One-liner for executives: A small, MIT-licensed add-on that gives our admin a "which branch/region/department am I working in?" switcher — one that sticks between sessions, travels in URLs, and filters every screen automatically. Roughly days of work instead of weeks, no new infrastructure, no schema migration required.

What it delivers: users pick a sub-scope in the topbar and lists, widgets, navigation counts, and global search all narrow to it — without us editing individual resources. It remembers the choice across navigation and logout, and links can carry the scope so people can share "my region" views directly. Two configuration points total: a plugin registration and a trait-plus-array per resource.

What it is not — say this out loud in the room: it's a working context, not a security boundary. Permissions still have to be enforced elsewhere. And because it's panel-aware by design, background jobs and exports will see the full dataset unless we handle them deliberately. If a stakeholder hears "tenancy" and assumes "isolation", correct it now, not in the incident review.

Engineering summary: composer require, one plugin registration with a ->scopes([...]) array, one @source line in the panel theme, one trait plus a static FK map per opted-in resource. Custom join logic is supported when the FK isn't on the model. The dropdown is relocatable and replaceable (renderHook, withoutDropdown, publishable view). Global scope is per-model, so treat adoption as a domain cutover with tests, not a per-screen toggle.

Risk statement for the record: young package (v1.x, ~30 stars, no dependents, single maintainer), so pin the version and keep the fork option open — MIT makes that cheap. The two design characteristics to design around are the per-model blast radius and the unscoped execution contexts. Both are documented, neither is a defect, and both are cheap to accommodate if we decide on them up front.