# ListRoles

## Overview

ListRoles retrieves all roles in the system with optional filtering by status. This query supports administrative workflows such as access reviews, role audits, and identifying inactive roles during organizational restructuring.

## Business Rules

- Returns all Role records when no filters are provided
- Optional filters:
  - `status` — filter by ACTIVE or INACTIVE
- Returns full role records including name, status, and permissions array
- Returns an empty list if no roles match the filters

## Process Flow

```mermaid
flowchart TD
    A[Receive request] --> B{Status filter provided?}
    B -->|Yes| C[Apply status filter to query]
    B -->|No| D[Return all roles]
    C --> D
    D --> E[Return role list]
```

## External Dependencies

- None

## Error Scenarios

- **EMPTY_RESULT**: No roles match the given criteria — returns empty list

## Test Cases

- returns all roles when no filters applied
- returns roles filtered by ACTIVE status
- returns roles filtered by INACTIVE status
- returns empty list when no roles exist
- returns empty list when no roles match the status filter