# Role

## Description

Role represents a named authorization entity that holds a `permissions` array and can be assigned to users. Roles provide a level of abstraction between permissions and users, simplifying access management by allowing administrators to manage access at the role level rather than per-user. Common examples include "Sales Representative", "Sales Manager", or "Administrator".

Roles follow the principle of least privilege, bundling only the permissions necessary for a specific job function.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Active: createRole
    Active --> Inactive: deactivateRole
    Inactive --> Active: reactivateRole
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| deactivate | ACTIVE | INACTIVE | [deactivateRole](../command/DeactivateRole.md) |
| reactivate | INACTIVE | ACTIVE | [reactivateRole](../command/ReactivateRole.md) |

### Command Definitions

- [createRole](../command/CreateRole.md)
- [updateRole](../command/UpdateRole.md)
- [deactivateRole](../command/DeactivateRole.md)
- [reactivateRole](../command/ReactivateRole.md)
- [grantPermissionToRole](../command/GrantPermissionToRole.md)
- [revokePermissionFromRole](../command/RevokePermissionFromRole.md)

### Query Definitions

- [listRoles](../query/ListRoles.md)
- [listUserRolesByRole](../query/ListUserRolesByRole.md)
- [listUsersByRole](../query/ListUsersByRole.md)

### Models

- Role

### Invariants

- Role name must be unique across all roles
- Role name is required and cannot be empty
- Status must be one of ACTIVE or INACTIVE
- Only ACTIVE roles can be assigned to users
- Only ACTIVE roles can receive permission grants
- Only ACTIVE roles can be updated (name/description)
- Deactivation requires no active UserRole assignments (ROLE_HAS_ACTIVE_ASSIGNMENTS guard)

### Relationships

- **Has Many UserRoles**: Role is assigned to users through UserRole join records