Jetstream Built-in Teams vs Custom Hierarchical Multi-tenancy for Nested Organizations

Answer to the Question

For a shared‑database application that needs divisions, sub‑teams, and cascading roles, the best trade‑off is to extend Jetstream’s built‑in Teams feature with a closure table (or materialized path) and a dedicated PermissionService. This keeps the current_team_id workflow, team‑switching UI, invitation flow, and API‑token scoping untouched, while adding the hierarchy logic only where it is needed. A separate multi‑tenancy layer (e.g., stancl/tenancy) introduces a second tenancy context that must be kept in sync with Jetstream, adds routing and database‑separation complexity, and forces you to rebuild much of the existing Jetstream UI and authorization logic.

Why the Extension Path Wins

• Minimal UI friction: Jetstream’s dropdown, team‑switcher, and profile‑photo handling already rely on current_team_id. Adding a parent_team_id or hierarchy_path column does not change that UI.
• Single authentication context: All Jetstream features, including personal access tokens that store a team_id, continue to work. The PermissionService simply starts from the token’s team and walks up the hierarchy.
• Controlled complexity: Only the authorization layer (Policies, Gates, and a custom HierarchicalGate) needs to be updated. All other Jetstream logic remains untouched.
• Testability: You can run Jetstream’s own feature tests after adding the closure table to catch regressions in team‑switching, deletion, and invitation flows.

When a Separate Tenancy Layer Might Be Considered

• When each division truly needs isolated databases or isolated hostnames.
• When you plan to support multi‑tenant SaaS with strict data isolation per tenant.
• When the hierarchy is so deep that you want to rely on database‑level partitioning for performance.

In the scenario described—shared‑database nested organizations with cascading permissions—those use‑cases are not present, so the extension approach is the leaner, more maintainable choice.

Concrete Steps for the Extension Path

1. Create the hierarchy table:

   CREATE TABLE team_ancestors (
       ancestor_id BIGINT UNSIGNED NOT NULL,
       descendant_id BIGINT UNSIGNED NOT NULL,
       depth INT NOT NULL,
       PRIMARY KEY (ancestor_id, descendant_id)
   );

   Use a closure table so that queries for ancestors or descendants are O(1) with a single index.
2. Modify the Team model to maintain the closure table on create, update, and delete. Wrap these operations in a transaction to avoid orphaned rows.
3. Override currentTeam() only when necessary to return the active team plus its ancestors. The override should call the parent method and then fetch the ancestor chain via the closure table.
4. Implement PermissionService:
   • Accept a Team (or token’s team) and walk up the ancestor chain, merging role‑based permissions.
   • Cache the resolved permission set per request to avoid repeated DB hits.
5. Wrap Gates/Policies with a HierarchicalGate that delegates to PermissionService::allows.
   • Keep existing policy signatures; just add a docblock noting that the team context may include ancestors.
6. Update tests:
   • Write new feature tests for a two‑level hierarchy and a three‑level hierarchy, verifying that the team‑switcher UI shows the correct active team.
   • Run php artisan test --filter=Team to ensure Jetstream’s own tests still pass.
7. Verify token scoping:
   • When creating a personal access token, keep team_id pointing to the leaf team.
   • Ensure tokenCan uses PermissionService to resolve ancestor permissions.
8. Deploy and monitor:
   • Check that invitations still target the intended team ID and that the invited user receives the correct role hierarchy.
   • Monitor query counts for permission checks to confirm O(depth) performance.

Potential Missing Detail

If your application requires a user to be “active” in multiple teams at the same time (e.g., a dashboard that shows data from several divisions simultaneously), you may need a different approach such as a separate tenancy context or a custom multi‑active team resolver. Let me know if that scenario applies, and we can adjust the recommendation accordingly.