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.

---

👨‍💻 6. Lead Engineering & Technical Architecture Credits

• Engineering Firm: Okyere Jay Technologies
• Consultancy Portal: okyerejayconsult.tech
• Technical Support Email: hello@johnokyere.xyz
• Lead Architect: John Okyere
• Maintenance Policy: For system expansions, third-party ERP integrations, or high-availability deployments, contact the technology desk at hello@johnokyere.xyz.

---

🛡️ 7. Developer Admin Panel & Financial RBAC Isolation System

The platform provides a dedicated, isolated Developer Control Panel (/developer) engineered specifically for technical consultants, external engineers, and DevOps support teams.

7.1 Financial & Commercial Isolation Policy

To protect commercial privacy, store turnover, POS cash balances, and customer financial payment records, accounts assigned the developer role are strictly isolated:

• Zero Financial Access: Developer accounts cannot view or query sales reports (/admin/reports), financial ledgers (/admin/payments), register cash drawers (/admin/pos), or executive revenue summaries (/admin/dashboard).
• Middleware Isolation: AdminMiddleware detects developer accounts and redirects them directly to the developer control console with a security warning.
• Dedicated Routing Group: Developer operations are routed under /developer/* protected by DeveloperMiddleware.
• Dual Super Admin Access: Super Administrators have access to both the executive administration console and the developer console.

7.2 Developer Control Tools

Module	Endpoint	Purpose & Capabilities
Health Overview	/developer	System telemetry, PHP runtime, memory limit, DB latency, queue health, cache status.
Logs & Exceptions	/developer/logs	Real-time laravel.log inspector, stack trace viewer, level filtering (Error, Warning, Info), and log truncation.
Database & Schema	/developer/database	Database connection status, table inventory & row counts, migration status, and PRAGMA integrity probe.
Cache & Performance	/developer/cache	Targeted flushes for application cache, compiled views, routing tables, and configuration cache.
Queue & Recovery	/developer/queue	Inspect queued tasks, poison-pill failed jobs table, retry individual or all failed jobs, and restart daemons.
Maintenance Console	/developer/maintenance	Whitelisted safe Artisan commands execution (platform:test-all, optimize:clear, schedule:list, etc.) with terminal output.
System Audit Trail	/developer/audit	Technical audit event stream filtered to exclude customer checkout and payment details.
Developer Accounts & RBAC	/developer/access	Super Admin-only console for creating developer logins, managing granular RBAC, and revoking credentials.

7.3 Granular Developer RBAC Privileges

Super Administrators can grant fine-grained permissions when provisioning developer logins:

• dev.diagnostics: System environment, PHP runtime, and infrastructure telemetry.
• dev.logs: Application log viewer and exception inspection.
• dev.database: Database schema inventory and migration status.
• dev.cache: Cache engine flush and optimization tools.
• dev.queue: Queue job recovery, failed task retry, and daemon management.
• dev.maintenance: Whitelisted safe maintenance console commands.
• dev.audit: Technical system audit event stream.

7.4 Production Container Session Preservation on Cache Flushes

On containerized cloud hosts (Render, Docker, AWS ECS), running php artisan optimize:clear or config:clear removes bootstrap/cache/config.php. If unhandled, the live PHP-FPM runtime loses immediate access to environment keys (including APP_KEY), causing session cookie decryption failures and abruptly logging the operator out.

• Automatic Re-Warming: CacheController and MaintenanceController automatically re-execute config:cache and route:cache within the same transaction in production.
• Result: Caches are cleared and refreshed atomically without terminating authenticated sessions or corrupting runtime encryption.

7.5 Maintenance Console Safety & Route Inspection Guard

• Laravel 11/12 Route Listing: Replaced deprecated --compact with --except-vendor (php artisan route:list --except-vendor), generating a clean map of application handlers while omitting third-party vendor routes.
• Router Middleware Group Restoration: By default, Laravel's RouteListCommand calls $router->flushMiddlewareGroups(). When invoked through an HTTP controller, this would otherwise strip the web group before the HTTP kernel could terminate the request, leading to Target class [web] does not exist. MaintenanceController::runCommand() captures $router->getMiddlewareGroups() before execution and restores them in a finally block, guaranteeing zero request lifecycle side-effects.

7.6 2-Column Responsive Dashboard Architecture

The Developer Control Console uses the 2-column dashboard pattern:

• Left Column: Sticky, full-height desktop sidebar (lg:sticky lg:top-0 lg:h-screen lg:shrink-0 w-64) with its own header, environment status badges, and independent vertical scrolling (overflow-y-auto flex-1 overscroll-contain).
• Mobile Off-Canvas Drawer: On viewports < 1024px, converts to a slide-out drawer (fixed inset-y-0 left-0 z-50 w-64) with backdrop tap-dismissal (@click="sidebarOpen = false") and dedicated close button.
• Right Column: Pinned top header (sticky top-0 z-30 h-16) containing security isolation badges, storefront quick link, and safe sign-out menu with confirmation modal.