Future Developers & Maintainers Engineering 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:

# 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:

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:

# 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:

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:

# 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:

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:

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.