# RBAC & Permission Architecture Standard

## 1. Core Principle

Authorization must be explicit, centralized, scalable, and testable.

Do not scatter permission logic throughout controllers and services.

---

## 2. Permission Hierarchy

The system should support concepts such as:

```text
Module
  ↓
Menu
  ↓
Resource
  ↓
Action
```

Examples:

```text
HR
 └── Employee
      ├── employee.view
      ├── employee.create
      ├── employee.update
      └── employee.delete
```

---

## 3. Permission Naming

Use predictable permission names.

Recommended:

```text
module.resource.action
```

Examples:

```text
hr.employee.view
hr.employee.create
hr.employee.update
hr.employee.delete
payroll.salary.approve
project.contract.assign
```

Avoid inconsistent names such as:

```text
canCreateEmployee
employee_add_permission
create_employee_data
```

---

## 4. Authorization Boundary

Authorization may be enforced through:

- Middleware
- Policy
- Gate
- Permission service

Controllers should not contain repeated manual permission logic.

---

## 5. Role vs Permission

Role represents a group of responsibilities.

Permission represents an allowed action.

Do not create unnecessary roles for every action.

Example:

```text
Role:
Project Manager

Permissions:
project.view
project.update
contract.view
contract.assign
```

---

## 6. Allow/Deny Overrides

If the system supports permission overrides:

```text
Role Permission
      ↓
User Override
      ↓
Effective Permission
```

The resolution order must be deterministic.

Do not implement ad-hoc permission checks in individual controllers.

---

## 7. Permission Matrix

Permission resolution should be optimized.

Avoid loading the complete permission matrix repeatedly.

Avoid N+1 permission queries.

Prefer:

- eager loading
- bulk queries
- caching
- precomputed effective permissions where appropriate

---

## 8. Cache

Permission cache must have:

- Clear invalidation strategy
- Role-change invalidation
- Permission-change invalidation
- User override invalidation

Never cache authorization indefinitely without an invalidation strategy.

---

## 9. Service-Level Authorization

Critical business operations may require service-level authorization in addition to route-level authorization.

Example:

```text
Route permission:
contract.approve

Service business rule:
Only assigned approver can approve.
```

Permission answers:

```text
Can this user perform this type of action?
```

Business rule answers:

```text
Can this user perform it on this specific entity right now?
```

Keep these concepts separate.

---

## 10. Permission Changes

Permission changes are write operations and must use transactions.

Changes involving:

- Roles
- Permissions
- User assignments
- Overrides

must be atomic.

---

## 11. Testing

Every critical permission must have tests for:

- Allowed
- Denied
- Role-based access
- Override
- Missing permission
- Invalid resource access

---

## 12. Golden Rule

Never solve an RBAC problem by adding:

```php
if ($user->role === 'admin')
```

unless the domain explicitly requires a true system-level role.

Prefer capability-based authorization.