# Email Verification Module Usage Instructions

> The `feat/email-must-verify` branch introduces a robust and secure Email Verification flow. Integrated seamlessly with the `base` branch, it guarantees that users (and optionally admins) verify their email addresses before accessing protected routes in the application.

---

## Table of Contents

1. [Module Overview](#1-module-overview)
2. [What You Inherit](#2-what-you-inherit)
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)

---

## 1. Module Overview

This module enforces email ownership. When a user registers (or if an existing user hasn't verified their email), the application will lock them into a "Verification Notice" screen. They must click a securely signed link sent to their inbox to proceed to their dashboard.

---

## 2. What You Inherit

By merging with the **Base** branch, this feature inherits:
- **UI Consistency:** The verification notice screen utilizes the standard authentication layout inherited from the base branch.
- **Frontend Interactivity:** The "Resend Verification Email" button utilizes Alpine.js and Axios for smooth, reload-free interactions.
- **Eloquent Standards:** Modifies the base `User` model to fully embrace Laravel's native `MustVerifyEmail` contract and custom notification logic.

---

## 3. Deep Dive: Features & Functionality

This branch brings essential onboarding security features:

- **Mandatory Verification Middleware:**
  Includes the `EnsureEmailIsVerified` middleware. If applied to a route, unverified users are forcefully redirected to the `verification.notice` screen.
- **Secure Signed Links:**
  Verification emails contain a Laravel `temporarySignedRoute`. This ensures the link cannot be tampered with and automatically expires after a configured duration (default 60 minutes).
- **Dual-Guard Support:**
  The `EmailVerificationController` dynamically detects if the user is an `admin` or a regular `user`. It routes the user back to the correct dashboard (`/admin/dashboard` vs `/account/dashboard`) upon successful verification.
- **AJAX Resend with Throttling:**
  Users can click "Resend" if they didn't receive the email. This is handled via a JSON endpoint. To prevent email spam/abuse, the backend enforces a strict rate limit (throttle) before allowing another email to be dispatched.
- **Customized Email Template:**
  A beautifully styled Blade email template (`verify-email.blade.php`) matching the application's branding, overriding Laravel's default text emails.

---

## 4. File Paths & Architecture

Here are the key structural areas introduced:

### Routing & Middleware
- **`routes/email-verification.php`**: Contains the routes for both `admin` and `user` prefixes (`verification.notice`, `verification.verify`, `verification.send`).
- **`app/Http/Middleware/EnsureEmailIsVerified.php`**: The interceptor that checks `$user->hasVerifiedEmail()`.

### Controllers & Notifications
- **`app/Http/Controllers/EmailVerificationController.php`**: Handles rendering the notice, validating the signed URL hash, and processing AJAX resend requests with built-in Rate Limiting.
- **`app/Notifications/VerifyEmail.php`**: The queued notification class responsible for generating the signed URL and passing it to the email view.

### Views & Frontend
- **`resources/views/pages/email-verification/notice.blade.php`**: The UI prompting the user to check their inbox.
- **`resources/views/emails/auth/verify-email.blade.php`**: The HTML email template sent to the user.
- **`resources/js/email-verification/notice.js`**: The JavaScript logic handling the Resend button's loading state, success toasts, and countdown timers for throttling.

---

## 5. Step-by-Step Usage Guide

### 1. Database & Environment Setup
Make sure your email SMTP settings are configured in your `.env` file (e.g., Mailtrap, Mailgun, AWS SES) so the emails actually send:
```env
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
```

### 2. Protecting Routes
To require email verification on any route or route group, simply attach the middleware alias (usually `verified` depending on your `bootstrap/app.php` setup, or explicitly `\App\Http\Middleware\EnsureEmailIsVerified::class`).
```php
Route::middleware(['auth:user', 'verified'])->group(function () {
    Route::get('/dashboard', ...);
});
```

### 3. Testing the Flow
- Register a new account or manually set `email_verified_at = null` in the database for an existing user.
- Attempt to access a protected dashboard route. You will be redirected to the verification notice screen.
- Click the "Resend Email" button to test the AJAX throttling.
- Check your email inbox (or Mailtrap), click the "Verify Email Address" button in the email, and watch as you are successfully authenticated and redirected to the dashboard.