# Admin Module Usage Instructions > The `feat/admin` branch introduces the secure, foundational Admin Portal for the application. Built on top of the base branch architecture, it delivers a fully functional authentication flow, a hidden login route for enhanced security, a profile management feature, and a primary dashboard shell ready for your CRUD modules. --- ## Table of Contents 1. [Module Overview](#1-module-overview) 2. [What You Inherit (Base Branch Merge)](#2-what-you-inherit-base-branch-merge) 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 & Customization Goals](#6-security--customization-goals) --- ## 1. Module Overview This branch establishes the core Admin area. It provides the initial point of entry for administrators, complete with secure sessions, robust password recovery (Forgot/Reset password), and a dashboard view. It acts as the secure container where all future administrative management modules (like Users, Blogs, CMS, Settings) will be nested and protected. --- ## 2. What You Inherit (Base Branch Merge) Because this branch merges with our **Base Branch**, you inherit: - **The UI Component Library:** All ``, ``, and `` Blade components used to style the auth screens. - **The Core Architecture:** The central `AuthenticatesUsers` trait located in `app/Traits/AuthenticatesUsers.php`. This trait powers the underlying logic for logging in, rate-limiting, and managing active status. - **Pre-configured Tooling:** Tailwind CSS, Alpine.js, and Vite perfectly set up for frontend development without starting from scratch. --- ## 3. Deep Dive: Features & Functionality This branch introduces sophisticated features specifically tailored for the administrative experience: - **Hidden Login Route (Security via Obscurity):** The login page is not accessible at a predictable URL like `/admin/login`. Instead, it uses a hidden alias prefix `/behindthescreen`. If an unauthorized user guesses the root `/admin` URL, they are simply redirected to `/admin/login`, but the actual form is served from `/behindthescreen`. - **Complete Auth Flow:** - **Login** (`/behindthescreen`): Supports both traditional HTML form submission and asynchronous JSON/AJAX login. - **Forgot Password** (`/admin/forgot-password`): Sends secure, temporary token links via email. - **Reset Password** (`/admin/reset-password/{token}`): Validates the token and updates the admin's credential. - **Secure Logout** (`/admin/logout`): Clears the session entirely and flushes cached credentials. - **Admin Dashboard Shell:** An authenticated landing page (`/admin/dashboard`). It serves as the home base displaying key metrics or welcome information post-login. - **Profile Management:** An integrated route and controller for changing the admin password (`/admin/profile/change-password`). - **Advanced Middleware Protection:** - **`auth:admin`**: Restricts the dashboard and profile routes strictly to users authenticated with the `admin` guard. - **`guest:admin`**: Ensures logged-in administrators cannot accidentally access the login or forgot-password forms again. - **`prevent-back-history`**: A custom middleware applied to authenticated routes. It prevents browsers from caching secured pages, so if an administrator logs out and someone clicks the browser's "Back" button, the sensitive dashboard data is not shown. --- ## 4. File Paths & Architecture Here are the key files introduced or modified in this branch, giving you a detailed look under the hood: ### Controllers (`app/Http/Controllers/Admin/Auth/`) - **`LoginController.php`**: Consumes the `AuthenticatesUsers` trait. Handles rate-limiting, traps authentication exceptions (`AuthenticationException`, `ThrottleRequestsException`), and formats error responses beautifully for AJAX requests. - **`ForgotPasswordController.php`**: Handles password reset link requests natively. - **`ResetPasswordController.php`**: Processes the actual password reset execution. - **`DashboardController.php`**: A clean, single-action controller serving the primary dashboard view. ### Routing (`routes/admin.php`) - **`routes/admin.php`**: The dedicated routing file for all admin-facing endpoints. It is wrapped in the `admin.` name prefix automatically, meaning `route('admin.dashboard')` maps cleanly. ### Views (`resources/views/pages/admin/`) - **`auth/login.blade.php`**: The stylized admin login screen, utilizing base form components and Alpine.js for seamless interactions. - **`auth/forgot-password.blade.php`**: The password recovery request form. - **`auth/reset-password.blade.php`**: The new password entry form. - **`dashboard/index.blade.php`**: The main dashboard shell where admin widgets, charts, and quick links will be placed. --- ## 5. Step-by-Step Usage Guide ### 1. Database Seeding & Initialization Before testing the portal, ensure your database has an admin user to log in with. Run your migrations and seeders: ```bash php artisan migrate:fresh --seed ``` ### 2. Accessing the Portal Navigate your browser to `http://your-app-url/behindthescreen` to access the login page. *Note: Do not try to access `/admin/login` directly—the hidden alias provides an extra layer of security against automated bots.* ### 3. Authentication Testing Log in using your seeded administrator credentials. - Try entering a wrong password 5 times to see the **rate-limiting / throttling** feature in action. - Try submitting the form normally or via AJAX (if configured) to see the dual-response logic in the `LoginController`. ### 4. Extending the Admin Module When creating new pages for the admin panel (e.g., adding a "Categories" management page): 1. **Views:** Place your new views inside `resources/views/pages/admin/categories/`. 2. **Routes:** Add your new routes in `routes/admin.php` exclusively inside the `Route::middleware('auth:admin')` group to ensure they are protected. 3. **Controllers:** Place new administrative controllers inside `app/Http/Controllers/Admin/`. --- ## 6. Security & Customization Goals - **Total Isolation:** The primary goal of this branch is to separate the admin context completely from the standard public user context. It uses distinct route files (`admin.php`), a dedicated authentication guard (`admin`), and an obfuscated login path. - **Design Consistency:** The login screens and dashboard utilize the Base Branch component library. You can easily modify the look and feel by adjusting the `` Blade components or Tailwind classes without having to rewrite or touch the underlying, secure authentication logic.