# Base Branch Usage Guide

> The definitive starting point for all new features. This base branch provides a pre-configured Laravel 13 architecture, a comprehensive UI component library, and standardized utility classes, allowing you to bypass boilerplate and focus directly on building specific CRUD operations and business logic.

---

## Table of Contents

1. [Branch Philosophy](#1-branch-philosophy)
2. [What You Inherit](#2-what-you-inherit)
3. [Local Development Setup](#3-local-development-setup)
4. [Component Quick Reference](#4-component-quick-reference)
5. [Application Core Setup](#5-application-core-setup)
6. [Feature Development Workflow](#6-feature-development-workflow)

---

## 1. Branch Philosophy

This branch is a **clean slate**. It intentionally omits specific CRUD modules (like Users, Blogs, Categories) to serve as a pure foundation. 

**The Goal:** When you create a new feature branch from this base, you start with a fully functional UI system, authentication foundation, and error handling structure, completely eliminating repetitive setup tasks.

---

## 2. What You Inherit

By merging or branching from this base, your environment comes pre-loaded with:

- **Component Library:** 70+ robust Blade components (`resources/views/components/`) including datatables, forms, dialogs, and utility widgets.
- **Base Layouts & Pages:** Standard error pages (404, 500), a maintenance view, and a default home layout.
- **Core Utility Controllers:** Pre-built controllers like `TinyMceController` for image handling and `ChangePasswordController`.
- **Global Helper Utilities:** Carbon-powered date formatters and phone formatters accessible from anywhere.
- **Styling Configuration:** Tailwind CSS customized with specific brand primary and surface color tokens, plus Alpine.js configured for interactivity.

---

## 3. Local Development Setup

Follow these exact steps to pull down the base branch and initialize it on your local machine:

### 1. Clone & Checkout
```bash
git clone <repository-url>
cd <project-directory>
git checkout <base-branch-name>
```

### 2. Install Dependencies
```bash
composer install
npm install
```

### 3. Environment Configuration
Copy the sample environment file and update your database credentials:
```bash
cp .env.example .env
php artisan key:generate
```

### 4. Serve the Application
Run both the Laravel PHP server and Vite asset bundler concurrently:
```bash
composer dev
```
*(If preferred, you can run `php artisan serve` and `npm run dev` in separate terminal tabs).*

---

## 4. Component Quick Reference

To maintain UI consistency, always use the provided `x-` components rather than raw HTML.

### Layout & Tables
| Component | Tag | Usage |
| :--- | :--- | :--- |
| **Server Table** | `<x-common.table-server>` | Standardize table layouts; wrap your `<thead>` and `<tbody>` inside. |
| **Pagination** | `<x-ajax-pagination>` | Place at the bottom of data views for asynchronous page navigation. |
| **Empty State** | `<x-no-data-available>` | Render conditionally (`@if($items->isEmpty())`) when lists return empty. |

### Forms
| Component | Tag | Usage |
| :--- | :--- | :--- |
| **Input** | `<x-forms.input>` | Standard text/email fields with automatic error state handling. |
| **Select** | `<x-forms.select>` | Uniform dropdown menus. |
| **Checkbox** | `<x-forms.checkbox>`| Styled checkboxes with integrated labels. |

### Feedback & Actions
| Component | Tag | Usage |
| :--- | :--- | :--- |
| **Buttons** | `<x-buttons.primary>` | Standard action buttons (`primary`, `secondary`, `danger` variants). |
| **Alert Dialog**| `<x-alert-dialog>` | A reusable Alpine.js modal for critical confirmations (like deletions). |

---

## 5. Application Core Setup

This branch handles the heavy lifting for common application requirements in the `app/` directory:

- **Authentication (`app/Traits/AuthenticatesUsers.php`):** A unified trait handling standard authentication flows. It seamlessly manages login (with role-based guard support, active status checks, and rate-limiting/throttling), user registration, logout, and password resets.
- **Helpers (`app/Helpers/functions.php`):** Centralized global helper functions (e.g., `format_phone`, `format_date` using Carbon) available anywhere in the application.

---

## 6. Feature Development Workflow

When you are assigned a new module (e.g., building a "Products" CRUD):

1. **Branch Off:** Create a new branch directly from this base branch (`git checkout -b feature/product-crud base-branch-name`).
2. **Build the Backend:** Create your Model, Migration, and Controller as usual.
3. **Use the Components:** In your Blade views, exclusively use the `<x-common.*>`, `<x-forms.*>`, and `<x-buttons.*>` components to build the frontend.
4. **Implement AJAX:** For data tables, return JSON from your controller and utilize Alpine.js and `<x-common.table-server>` to render the views without full page reloads.

> **Rule of Thumb:** If you find yourself writing raw HTML for an input field, table row, or button, check the `resources/views/components/` folder first. There is almost certainly a component already built for it.