# Admin Profile Module Usage Instructions

> The `feat/admin-sub/profile` branch introduces a complete, AJAX-powered Profile Management system for administrators. Merging seamlessly with the base and admin auth branches, it allows users to update their personal information and manage their avatar securely without page reloads.

---

## Table of Contents

1. [Module Overview & Goals](#1-module-overview--goals)
2. [What You Inherit (Merge Context)](#2-what-you-inherit-merge-context)
3. [Deep Dive: Features & Functionality](#3-deep-dive-features--functionality)
4. [File Paths & Architecture](#4-file-paths--architecture)
5. [Step-by-Step Usage Guide](#5-step-by-step-usage-guide)
6. [Security & Best Practices](#6-security--best-practices)

---

## 1. Module Overview & Goals

The goal of this module is to provide authenticated administrators with a dedicated interface to manage their account details. This includes updating their name and email, as well as uploading or removing a profile avatar.

Instead of full page submissions, this module is engineered to handle form submissions via AJAX, returning clean JSON responses that instantly update the UI (like updating the user's name or avatar in the top navigation bar).

---

## 2. What You Inherit (Merge Context)

This branch builds on top of `base` and `feat/admin`. By merging this, your environment inherits:

- **Base Components:** All the Tailwind/Alpine Blade components (forms, buttons, modals, toasts).
- **Admin Auth Flow:** The secure login, dashboard, and password reset functionalities.
- **Profile Module:** The new profile views, dedicated controllers, FormRequests for validation, and a Service class for business logic abstraction.

---

## 3. Deep Dive: Features & Functionality

This branch adds sophisticated profile management features:

- **AJAX Profile Updates:**
  Administrators can update their profile information. The `ProfileController@update` returns the updated `initials`, `fullName`, and `email` in JSON format, allowing the frontend to immediately reflect changes without a refresh.
- **Avatar Management:**
  - **Upload Avatar:** A dedicated endpoint to securely handle file uploads, validating the image and storing it via the `ProfileService`.
  - **Remove Avatar:** An endpoint to delete the current avatar and revert to the default initials/placeholder.
- **Service Layer Abstraction:**
  Business logic (like file handling and database updates) is separated from the controller and placed into `App\Services\Admin\ProfileService`. This keeps the controller incredibly thin and focused strictly on HTTP request/response handling.

- **Dedicated Validation (FormRequests):**
  Uses `ProfileRequest` to validate name/email updates and `UploadProfileImage` to strictly validate image mimetypes and file sizes before hitting the controller.

---

## 4. File Paths & Architecture

Here are the key files introduced in this branch:

### Controllers & Services

- **`app/Http/Controllers/Admin/Profile/ProfileController.php`**: The primary controller handling the profile UI and AJAX endpoints.
- **`app/Services/Admin/ProfileService.php`**: The service class encapsulating the business logic for updating the database and handling file storage.

### Validation Requests

- **`app/Http/Requests/Profile/ProfileRequest.php`**: Validates the profile update form (ensuring unique emails, valid strings, etc.).
- **`app/Http/Requests/Profile/UploadProfileImage.php`**: Validates the avatar upload form (ensuring it is an image, within size limits).

### Routing

- **`routes/admin.php`**: Added a new `Route::prefix('profile')` group under the authenticated admin middleware.
  - `GET /admin/profile` -> Profile UI
  - `POST /admin/profile` -> Update Profile
  - `POST /admin/profile/avatar` -> Upload Avatar
  - `DELETE /admin/profile/avatar` -> Remove Avatar

### Views

- **`resources/views/pages/admin/profile/admin-index.blade.php`**: The user interface for the profile page, built using base form components and designed for AJAX interactions.

---

## 5. Step-by-Step Usage Guide

### 1. Accessing the Profile Page

Log in to the admin portal via `/behindthescreen`. From the dashboard, navigate to `http://your-app-url/admin/profile` (or click the profile link in the navigation/sidebar).

### 2. Updating Profile Details

Fill out the profile form (Name, Email) and submit.

- **Validation Testing:** Try entering an invalid email or an email that already exists in the database to see the FormRequest validation errors handled gracefully.
- **Success:** On success, a toast notification will appear, and the controller will return the new user data in JSON format.

### 3. Managing the Avatar

- **Upload:** Select an image file and upload it. The `ProfileService` will store the file and update the user's avatar path. The UI will instantly display the newly uploaded image.
- **Remove:** Click the remove/delete button on the avatar. It will trigger a `DELETE` request, clearing the file and reverting the UI to display the user's initials.

---

## 6. Security & Best Practices

- **Role Parameter Injection:** The routes utilize Laravel's `->defaults('role', 'admin')` to implicitly pass the current guard role to the controllers and services. This makes the `ProfileService` highly reusable; if you later build a standard `User` profile page, you can reuse the exact same service by simply passing `'web'` instead of `'admin'`.
- **Thin Controllers:** The `ProfileController` delegates all complex operations to `ProfileService`, adhering to the Single Responsibility Principle and making the codebase much easier to test.
- **Strict Validation:** Using dedicated FormRequests ensures that malicious payloads never reach the controller or service layer.