> For the complete documentation index, see [llms.txt](https://docs.enicebakerygh.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enicebakerygh.com/architecture-and-engineering/developer-handbook.md).

# Developers & Maintainers Handbook

Welcome to the technical engineering manual for **Eniceberny Bakery and Culinary Hub**. This handbook is authored for software engineers, DevOps maintainers, and architectural contributors tasked with maintaining, scaling, or integrating with the codebase.

***

## 🧭 1. Repository Anatomy & Directory Map

```
├── app/
│   ├── Enums/                # Backed enums (UserRole, OrderStatus, etc.)
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Admin/        # Operational consoles (Orders, POS, Products, Settings, Reports)
│   │   │   ├── Auth/         # Authentication, OTP email verification
│   │   │   └── Storefront/   # Public commerce (Shop, Cart, Checkout, Invoices, Catering, Docs)
│   │   ├── Middleware/       # Security (AdminMiddleware, RoleGates, TrustedProxies)
│   │   └── Requests/         # Form validation rules (CheckoutRequest, ProductRequest, etc.)
│   ├── Models/               # Eloquent ORM models with relations, casts, and audit logs
│   ├── Services/             # Domain business logic (OrderService, CartService, Payments, Settings)
│   └── helpers.php           # Global presentation helpers (format_currency, site_logo_url, etc.)
├── database/
│   ├── factories/            # Model factories for automated test generation
│   ├── migrations/           # Version-controlled schema migrations
│   └── seeders/              # Authentic culinary menu, category, and sample data seeders
├── docker/                   # Production Apache config, PHP.ini directives, and entrypoint.sh
├── docs/                     # GitBook documentation books (Markdown files & SUMMARY.md)
├── resources/
│   ├── js/                   # JavaScript entry point (Alpine.js, @gitbook/embed)
│   ├── css/                  # Styling & Tailwind design system
│   └── views/                # Modular Blade templates (Storefront, Admin, PDF, Emails)
├── routes/
│   ├── web.php               # Browser routes with CSRF and session cookies
│   └── api.php               # Stateless REST endpoints (/api/v1/*)
├── tests/
│   ├── Feature/              # Comprehensive HTTP and business workflow test suites (85 tests)
│   └── TestCase.php          # Base test harness with SQLite in-memory configuration
├── .github/workflows/ci.yml  # Automated GitHub Actions CI test & asset build pipeline
├── Dockerfile                # Production multi-stage Docker container build
├── gitbook-docs.yaml         # GitBook Site Git Sync configuration
└── render.yaml               # Render PaaS infrastructure as code blueprint
```

***

## ⚙️ 2. Local Development Environment Setup

### Prerequisites:

* **PHP**: `8.4.x` with extensions: `pdo_sqlite`, `pdo_pgsql`, `mbstring`, `bcmath`, `gd`, `zip`, `xml`, `curl`.
* **Composer**: `2.x`.
* **Node.js**: `20.x` or `22.x` and `npm`.

### Step-by-Step Setup:

```bash
# 1. Clone repository
git clone https://github.com/mhiskall282/enicebakery-website.git
cd enicebakery-website

# 2. Install PHP and NPM dependencies
composer install
npm install

# 3. Environment file configuration
cp .env.example .env
php artisan key:generate

# 4. Run database migrations and seed full operational catalog
php artisan migrate --seed

# 5. Build frontend Vite assets
npm run build

# 6. Run local development servers
# Terminal 1: Vite dev server with hot module reload
npm run dev

# Terminal 2: Local PHP web server
php artisan serve
```

***

## 🧩 3. Architectural Design Patterns & Domain Services

### 3.1 Order Service (`App\Services\Order\OrderService`)

The `OrderService` encapsulates transactional order placement, ensuring stock deductions, financial ledgers, and audit trails succeed atomically:

```php
public function createOrder(array $validatedData, Cart $cart, ?User $user = null): Order
{
    return DB::transaction(function () use ($validatedData, $cart, $user) {
        $order = Order::create([
            'order_number' => $this->generateOrderNumber(),
            'user_id' => $user?->id,
            'customer_name' => $validatedData['customer_name'],
            'customer_phone' => $validatedData['customer_phone'],
            'subtotal' => $cart->subtotal,
            'total' => $cart->total,
            'status' => 'pending',
            'payment_status' => 'pending',
        ]);

        foreach ($cart->items as $item) {
            $order->items()->create([
                'product_id' => $item->product_id,
                'product_name' => $item->product->name,
                'quantity' => $item->quantity,
                'unit_price' => $item->unit_price,
                'subtotal' => $item->subtotal,
            ]);

            // Decrement inventory if tracking is enabled
            if ($item->product->track_inventory) {
                $item->product->decrementStock($item->quantity, 'online_order');
            }
        }

        // Record initial status audit trail
        $order->statusHistories()->create([
            'from_status' => null,
            'to_status' => 'pending',
            'comment' => 'Order placed online by customer',
            'user_id' => $user?->id,
        ]);

        return $order;
    });
}
```

### 3.2 Payment Gateway Driver Pattern

Gateways are resolved dynamically through `App\Services\Payments\PaymentManager`:

* To add a new payment gateway (e.g. Hubtel, Slydepay):
  1. Create driver class implementing `PaymentGatewayInterface`.
  2. Register driver in `PaymentManager::driver()`.
  3. Add credentials to `config/services.php` and `.env.example`.

### 3.3 Dynamic Settings & Logo Management

* Settings are cached under the key `all_site_settings`.
* When settings or logos are updated in `/admin/settings`, the cache is invalidated immediately via `Cache::forget('all_site_settings')`.
* Twin keys automatically synchronize (e.g. updating `site_name` updates `business_name`).

***

## 🧪 4. Testing Protocols & CI Automation

All pull requests and commits are verified against **85 automated tests** in [`.github/workflows/ci.yml`](file:///c:/Users/user/Desktop/enicebakery-website/.github/workflows/ci.yml):

```bash
# Execute entire test suite locally
php artisan test

# Execute with coverage report (if xdebug/pcov installed)
php artisan test --coverage

# Filter tests by module
php artisan test --filter AdminTest
php artisan test --filter StorefrontTest
php artisan test --filter Phase2CommerceTest
```

### Pre-Commit Quality Gate:

Before pushing to `main`, verify:

1. `php artisan test` $\rightarrow$ 85 passed, 0 failures.
2. `npm run build` $\rightarrow$ Vite bundles compile cleanly without warnings.
3. `git status` $\rightarrow$ No untracked junk files or debug prints.

***

## 🛠️ 5. Operational Maintenance & Troubleshooting Runbook

### 5.1 Clearing and Re-Warming Caches

If changes to templates, routes, or configurations are not reflecting on production:

```bash
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear

# Re-optimize for production
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### 5.2 Background Queue Worker

The application uses background queues for email dispatches and PDF receipt generation:

```bash
# Start queue worker locally
php artisan queue:work --tries=3 --timeout=90

# Restart workers on production deploy
php artisan queue:restart
```

### 5.3 Storage Symlink Repair

If product images or brand logos return HTTP 404:

```bash
php artisan storage:link
```

Verify that `storage/app/public` is accessible via `public/storage`.

### 5.4 Database Migration & Seeding Reset (Local Dev Only)

To reset the development database and re-seed authentic sample business data:

```bash
php artisan migrate:fresh --seed
```

> \[!WARNING] **Never run `migrate:fresh` in production!** Always use `php artisan migrate --force` for incremental schema updates on production servers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.enicebakerygh.com/architecture-and-engineering/developer-handbook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.