# UC-02 Register User & Assign Role - Architectural Mapping

This document maps the visual components from the **UC-02 Register User & Assign Role** Use Case diagram to the Laravel backend implementation. The architecture strictly follows **SOLID** and **DRY** principles, as requested.

## 1. Actor: Admin
* **Role Protection**: The entire user management module is restricted strictly to the `Admin` role.
* **Middleware**: This is enforced at the routing level using `EnsureRoleMiddleware` (aliased as `role:Admin`). The route group (`Route::middleware(['role:Admin'])->group(...)`) ensures that any user without the Admin role attempting to access these endpoints will receive an HTTP 403 response.

## 2. "UC-02 Register New User" & API Endpoints ("POST /users", "POST /users/{id}/roles")
* **Controller Structure**: Handled by `app/Http/Controllers/Api/UserController.php`. Following the Single Responsibility Principle (SRP), this controller only handles the HTTP request/response lifecycle.
* **Routes**: Defined in `routes/api.php` as `Route::post('users', [UserController::class, 'store']);` and `Route::post('users/{id}/roles', [UserController::class, 'assignRole']);`.

## 3. "Fill User Details (Name/Email/Dept/Branch)" (<<include>>)
* **Request Validation (DRY)**: User input is validated through a dedicated Form Request class, `app/Http/Requests/StoreUserRequest.php`. This centralizes the validation logic (ensuring Name, Email, Dept, Branch are valid and correctly formatted), keeping the controller clean and adhering to DRY principles.

## 4. "Choose Assigned Role (PR/PRHeader/Quality/Admin)" (<<include>>)
* **Role Verification**: The assigned roles are verified against the Spatie Laravel-Permission package configurations and models. The `RoleAuthorizationService` or the controller leverages Spatie's API (`$user->assignRole($roles)`) to handle role assignment securely. 
* **Database Tables**: Maps to the `Role` and `UserRole` (or Spatie's `model_has_roles`) tables as defined in the ERD and models structure.

## 5. "Save User & UserRole Record"
* **Data Layer (Repository Pattern)**: As per the implementation guide, database interactions are abstracted via the Repository Pattern (e.g., `UserRepositoryInterface` and its Eloquent implementation). This ensures the business logic remains uncoupled from the Eloquent ORM.
* **Mass Assignment Protection**: The `ApplicationUser` model (`app/Models/ApplicationUser.php`) uses a strict `$fillable` array to allow saving only expected fields, mitigating mass assignment vulnerabilities.

## 6. "Activate / Deactivate User Account"
* **Endpoint**: Handled via `PATCH /users/{id}/toggle`. 
* **Implementation**: The `UserController::toggle` method triggers the service/repository to flip the `IsActive` flag (soft-disable) on the `ApplicationUser` record, leaving the record intact for audit purposes.
