Implementation Plan: Tenant RBAC v1

Branch: 065-tenant-rbac-v1 | Date: 2026-01-27 | Spec: spec.md Input: Feature specification from /specs/[###-feature-name]/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

This plan outlines the implementation of a capabilities-first Tenant RBAC system within the existing Laravel and Filament application. The primary requirement is to introduce granular, server-side enforced permissions for tenant users, managed through a new "Members" UI.

The technical approach involves:

Creating a tenant_memberships table to store user roles within each tenant.
Defining a central capability registry and mapping roles (Owner, Manager, Operator, Readonly) to specific capabilities.
Using Laravel Gates and Policies to enforce these capabilities throughout the application.
Building a Filament Relation Manager (MembersRelationManager) to provide a UI for Owners to manage tenant memberships.
Adding comprehensive feature and unit tests with Pest to ensure the RBAC system is secure and correct.

Technical Context

Language/Version: PHP 8.4+ Primary Dependencies: Laravel 12, Filament 5, Livewire 4, Pest 4 Storage: PostgreSQL Testing: Pest Target Platform: Web (Laravel application) Project Type: Web application Performance Goals: Membership/capability evaluation MUST be O(1) per request after initial load (NFR-001). Constraints: RBAC UI surfaces MUST be DB-only at render time (NFR-003). Scale/Scope: The system should be designed to handle a moderate number of tenants and users, with the potential to scale. Initial design should not be a bottleneck for future growth.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Inventory-first: N/A for this feature.
Read/write separation: All membership changes (write operations) are specified to require Owner-level privileges and will be implemented with confirmations and audit logs.
Graph contract path: N/A. The spec explicitly states no Graph calls for RBAC UI.
Deterministic capabilities: The role-to-capability mapping is deterministic and defined in a central place.
RBAC Standard: This feature implements the RBAC standard. It establishes the two-plane separation, capabilities-first authorization, and least-privilege roles.
Tenant isolation: All queries and actions are tenant-scoped through the tenant_memberships table.
Run observability: N/A for the core RBAC logic, as it's synchronous. Any long-running operations triggered by authorized users will follow this principle.
Automation: N/A for this feature.
Data minimization: The tenant_memberships table stores only essential information (IDs and role).
Badge semantics (BADGE-001): The role badge in the members list will use the BadgeCatalog.

Project Structure

Documentation (this feature)

specs/065-tenant-rbac-v1/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/
│   └── capabilities.md  # Phase 1 output
└── tasks.md             # Phase 2 output (/speckit.tasks command)

Source Code (repository root)

The project follows a standard Laravel structure. Key files for this feature will be located in:

app/
├── Models/
│   ├── TenantMembership.php   # New Eloquent model
│   └── User.php               # Add relationship to TenantMembership
│   └── Tenant.php             # Add relationship to TenantMembership
├── Policies/
│   └── TenantMembershipPolicy.php # New policy for managing memberships
├── Providers/
│   └── AuthServiceProvider.php    # Register gates and policies
└── Filament/
    └── Resources/
        └── TenantResource/
            └── RelationManagers/
                └── MembersRelationManager.php # New Filament relation manager

database/
├── factories/
│   └── TenantMembershipFactory.php # New model factory
└── migrations/
    └── [timestamp]_create_tenant_memberships_table.php # New migration

tests/
├── Feature/
│   └── Filament/
│       └── TenantMembersTest.php # New feature test for RBAC UI
└── Unit/
    └── TenantRBACTest.php      # New unit test for role-capability mapping

Structure Decision: The implementation will use the existing Laravel project structure. New classes and files will be created in their conventional locations. The primary UI for membership management will be a Filament Relation Manager on the TenantResource.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]

5.2 KiB Raw Blame History