# Administration Panel & Business Operations Manual

This document provides a comprehensive operational and technical manual for the administrative back-office of **Eniceberny Bakery and Culinary Hub**. It details every screen, table, filter, modal, form input, and button action across all administrative modules.

---

## 🧭 1. Executive Operations Dashboard (`/admin/dashboard`)

The dashboard connects directly to live database records without mock or synthetic figures, providing real-time visibility into daily trade.

```mermaid
graph LR
    subgraph Operational Metrics
        A[Today's Revenue]
        B[Gross Total Revenue]
        C[Pending Kitchen Dispatch]
        D[Active Catering Leads]
    end
    subgraph Channel Split
        E[Online Storefront Channel]
        F[POS Counter Channel]
    end
    subgraph Action Queues
        G[Live Incoming Orders Ledger]
        H[Low-Stock Inventory Alerts <= 5 units]
        I[Top-Selling Delicacies]
    end
```

### 1.1 Key Metrics Tracked
- **Today's Revenue Card**: Sum of all settled orders recorded today (`created_at = today()` and `payment_status = 'paid'`).
- **Total Gross Revenue Card**: Cumulative revenue settled across all channels since inception.
- **Pending Kitchen Dispatch Card**: Count of orders in `pending`, `confirmed`, or `preparing` status requiring kitchen action.
- **Active Catering Leads Card**: Count of unquoted inquiries (`catering_inquiries.status = 'pending'`).
- **Channel Performance Cards**:
  - **Online Storefront**: Gross sales and order volume originating from the website (`source = 'web'`).
  - **In-Store POS**: Gross sales and order volume originating from counter registers (`source = 'pos'`).
- **Low Stock Inventory Alert**: Displays an urgent alert banner when any catalog product drops to $\le 5$ units in stock.

---

## 📋 2. Order Management & Kitchen Queue (`/admin/orders`)

The order subsystem governs order lifecycle progression from initial placement to doorstep handoff.

```mermaid
stateDiagram-v2
    [*] --> Pending: Online Order Placed
    Pending --> Confirmed: Payment Verified / COD Approved
    Confirmed --> Preparing: Kitchen Begins Baking / Cooking
    Preparing --> ReadyForPickup: Food Boxed & Placed on Warm Counter
    ReadyForPickup --> OutForDelivery: Rider Collects Package
    ReadyForPickup --> Completed: Customer Collects in Person
    OutForDelivery --> Completed: Rider Delivers Package
    Pending --> Cancelled: Payment Timeout / Void
    Confirmed --> Cancelled: Customer Cancellation / Stockout
```

### 2.1 Order Index Filters & Search Bar
- **Search Bar**: Instant lookup by Order Number (e.g. `EB-20260927-1402`), customer name, or phone number.
- **Status Filter**: Dropdown filter for `All Statuses`, `Pending`, `Confirmed`, `Preparing`, `Ready for Pickup`, `Out for Delivery`, `Completed`, `Cancelled`.
- **Payment Status Filter**: Filter by `Paid`, `Pending`, or `Refunded`.
- **Channel Filter**: Filter by `Web Storefront` vs `POS Counter`.
- **Date Range Pickers**: Filter orders within specific calendar dates.

### 2.2 Order Detail Screen (`/admin/orders/{id}`)
- **Customer Information Card**: Displays name, phone number (with instant WhatsApp link), email, delivery address, landmark, and GhanaPostGPS address (`AK-039-2311`).
- **Order Items Table**: Lists delicacies, portion variants, unit price, quantity, line total, and custom preparation notes (e.g. *"Nut-free"*).
- **Financial Breakdown Card**: Subtotal, delivery fee, promotional discount applied, VAT/taxes, and final total.
- **Interactive Action Buttons**:
  - **Button: "Update Order Status"**: Opens status progression modal. Select new status (`confirmed`, `preparing`, `ready_for_pickup`, `out_for_delivery`, `completed`, `cancelled`) and enter optional staff audit notes.
  - **Button: "Print Thermal Receipt"**: Launches the 80mm ESC/POS thermal receipt pop-up.
  - **Button: "Print Kitchen Docket"**: Generates a simplified, high-contrast kitchen ticket showing only order number, table/pickup info, dishes, portion sizes, and chef notes.
  - **Button: "Download PDF Invoice"**: Generates official branded A4 tax invoice via DomPDF with embedded verification QR code.
  - **Button: "Verify with Gateway"**: Directly queries Paystack's REST API `/transaction/verify/:reference` to reconcile payments if the customer's network dropped before redirecting.
  - **Button: "Cancel Order"**: Safely voids the order, records cancellation reason, and restores inventory to stock.

---

## 🍽️ 3. Catalog & Products Management (`/admin/products`)

Governs all menu delicacies, pricing, recipes, portion variants, and photography.

### 3.1 Product Listing Table
- Displays product thumbnail, name, SKU code, primary category, base price, sale price, inventory count, and status badges.
- **Quick Action: "Toggle Status"**: One-tap toggle to immediately mark an item available or unavailable on the live website.

### 3.2 Product Creation & Edit Form (`/admin/products/create`)
- **Core Attributes**:
  - **Product Name**: Commercial title (e.g. *Party Jollof Rice & Roasted Chicken Platter*).
  - **Slug**: Auto-generated URL-safe identifier (e.g. `party-jollof-rice-roasted-chicken`).
  - **Category**: Select primary culinary department (Pastries, Continental, Ghanaian Cuisine, Celebration Cakes, Drinks).
  - **SKU**: Internal stock keeping unit (e.g. `CONT-JOL-001`).
  - **Base Price (`GH₵`)**: Standard selling price.
  - **Sale Price (`GH₵`)**: Optional promotional discounted price.
  - **Short Description**: 1-2 sentence summary displayed on menu cards.
  - **Full Description**: Rich culinary description, ingredients, and allergen advice.
- **Photography & Image Gallery**:
  - **Primary Image Upload**: File picker supporting JPG, PNG, WEBP (up to 5MB) with instant client-side preview.
  - **Gallery Images**: Multi-image uploader for cake angles and buffet presentations.
- **Portion & Size Variant Builder**:
  - Add multiple variations with separate prices and stock quantities (e.g. *6-inch Cake @ GH₵ 280*, *8-inch Cake @ GH₵ 400*, *10-inch Cake @ GH₵ 580*).
- **Customizable Options Builder**:
  - Add custom customer inputs: text inscriptions (e.g. *"Cake Inscription Text"*), select dropdowns (e.g. *"Frosting Flavor"*), or radio buttons.
- **Visibility & Promotion Flags**:
  - Checkbox: **Is Available** (controls public visibility).
  - Checkbox: **Is Featured** (displays in homepage chef highlights).
  - Checkbox: **Is Bestseller** (adds gold bestseller badge).
- **Button: "Save Product"**: Persists the product and its variants atomically within a database transaction.

---

## 📂 4. Category Management (`/admin/categories`)

- **Table View**: Lists categories with thumbnail, name, slug, sort order, and active product count.
- **Button: "Create Category"**: Modal capturing category name, slug, description, image, and numeric sort order.
- **Drag-and-Drop / Numeric Sort**: Controls the order in which categories appear in the storefront navigation bar and POS terminal tabs.

---

## 📦 5. Inventory Control & Movements (`/admin/inventory`)

Provides a comprehensive real-time audit ledger of all ingredient and baked good inventory movements.

### 5.1 Low-Stock Monitoring
- Products with stock levels $\le 5$ units are automatically highlighted in bold amber warnings.

### 5.2 Stock Movements Audit Log
Every change in stock is logged in the `inventory_movements` table with:
- **Timestamp**: Exact date and time of movement.
- **Product & SKU**: Affected item.
- **Movement Type**:
  - `pos_sale`: Deducted automatically upon counter sale completion.
  - `web_sale`: Deducted automatically upon online checkout.
  - `restock`: Fresh morning bakehouse batch added.
  - `waste_spoilage`: Expired, damaged, or dropped items discarded.
  - `adjustment`: Inventory count reconciliation.
- **Quantity Delta**: Numeric change (e.g. `-2` or `+24`).
- **Previous Stock $\rightarrow$ New Stock**: Stock transition snapshot.
- **Operator**: Name of the staff member or cashier who authorized the change.

### 5.3 Stock Adjustment Modal
- **Button: "Adjust Inventory"**:
  1. Select target product.
  2. Select movement reason (`restock`, `waste_spoilage`, `adjustment`).
  3. Enter quantity change.
  4. Enter mandatory explanation note (e.g. *"Morning oven batch - 30 meat pies baked"*).
  5. Click **"Apply Adjustment"**.

---

## 🏷️ 6. Promotions & Coupon Codes (`/admin/promotions`)

- **Table View**: Code, discount type (`percentage` vs `fixed_amount`), discount value, minimum order spend, total redemptions, redemption limit, start date, expiration date, and status.
- **Button: "Create Coupon"**:
  - **Coupon Code**: Unique alphanumeric string (e.g. `WELCOME10` or `ENICEVIP`).
  - **Discount Type**: Percentage off (e.g. `10%`) or Fixed Cedis off (e.g. `GH₵ 20.00`).
  - **Minimum Order Spend**: Minimum cart subtotal required to activate coupon.
  - **Maximum Uses**: Overall cap or per-customer limit.
  - **Active Toggle**: Enable or disable promotional code instantly.

---

## 💳 7. Payment Transactions Ledger (`/admin/payments`)

The centralized multi-channel financial ledger displaying every settlement across the enterprise.

- **Ledger Columns**: Order Number, Customer Name, Payment Gateway (`cash`, `momo`, `card`, `paystack`), External Transaction Reference, Amount (`GH₵`), Settlement Status (`success`, `pending`, `failed`), and Settlement Timestamp.
- **Filter Controls**: Filter by gateway, status, or date range.
- **Button: "Inspect Gateway Response"**: Opens a technical modal revealing raw JSON payloads from Paystack and telecom aggregators for audit verification.

---

## 👑 8. Catering Proposals & Quotation Engine (`/admin/quotes`)

Powers high-value corporate banquets, weddings, and executive event catering.

```mermaid
graph TD
    A[Patron Inquiry /catering] --> B[Admin Inquiries Queue /admin/catering]
    B --> C[Button: Draft Quote /admin/quotes/create]
    C --> D[Add Itemized Banquet Lines]
    D --> E[Button: Save & Send Quote]
    E --> F[Client Reviews Proposal QT-XXXX]
    F --> G[Client Approves & Pays 50% Milestone Deposit]
    G --> H[Button: Convert to Official Order]
    H --> I[Order Enters Kitchen Preparation Queue]
```

### 8.1 Quote Creation (`/admin/quotes/create`)
- **Customer & Event Information**: Client name, phone, email, event category (Wedding, Corporate, Birthday), target event date, venue location, and expected headcount.
- **Dynamic Line Item Builder**:
  - Add unlimited customized lines (e.g. *"Jollof & Grilled Chicken Buffet Buffet Station for 150 guests @ GH₵ 85/head"*).
  - Quantity, unit price, and auto-computed line totals.
- **Tax & Discount Controls**:
  - Apply custom promotional discounts.
  - Configure applicable VAT/levies.
- **Terms & Notes**: Payment schedule terms (50% deposit, 50% final balance), staffing notes, and dietary clauses.
- **Button: "Save Quotation"**: Generates a unique proposal number (e.g. `QT-260927-4F9A`).

### 8.2 Quote Actions
- **Button: "Print Formal Proposal"** (`/admin/quotes/{id}/print`): Generates a luxury branded quotation document suitable for corporate procurement boards.
- **Button: "Update Status"**: Set status to `draft`, `sent`, `accepted`, `rejected`, or `expired`.
- **Button: "Convert to Official Order"**: Once the 50% deposit is secured, clicking this button atomically converts the proposal into an official order (`order_type: catering`, `source: catering_quote`), copies all line items, and directs the operator straight to the fulfillment queue.

---

## 🎨 9. Content Management System (CMS) (`/admin/cms`)

Provides zero-code marketing control over the public storefront across six dedicated tabs:

1. **Tab 1: Homepage Sections (`/admin/cms?tab=sections`)**:
   - Reorder and toggle the 15 distinct sections of the homepage (Hero Banner, Highlights, Story, Menu Carousel, Banquet Specials, Reviews, FAQ, etc.).
   - Enable or disable seasonal sections with a single switch.
2. **Tab 2: Custom Pages (`/admin/cms?tab=pages`)**:
   - Create, edit, and publish bespoke editorial pages (About Us, Terms of Service, Privacy Policy, Delivery Policies) with rich HTML formatting and SEO meta tags.
3. **Tab 3: Hero Banners (`/admin/cms?tab=banners`)**:
   - Manage rotating promotional slides with headline text, supporting subtitles, Call to Action (CTA) button labels, target URLs, and background banner art.
4. **Tab 4: Testimonials (`/admin/cms?tab=testimonials`)**:
   - Publish verified customer reviews with guest names, corporate affiliations, star ratings (1 to 5), and review text.
5. **Tab 5: Gallery Lightbox (`/admin/cms?tab=gallery`)**:
   - Upload high-resolution photographs of wedding cakes, event setups, and fresh pastries for the interactive storefront lightbox grid.
6. **Tab 6: Frequently Asked Questions (`/admin/cms?tab=faqs`)**:
   - Manage categorized FAQ accordions for Ordering, Delivery, Payments, and Catering inquiries.

---

## 🖼️ 10. Digital Media Asset Library (`/admin/media`)

- Centralized storage repository for all digital assets across the platform.
- **Button: "Upload Media Asset"**: Drag and drop photos with automated MIME-type validation (`jpeg`, `png`, `webp`, `svg`).
- **Button: "Copy Asset URL"**: Copies the CDN/public URL to clipboard for use in CMS pages or social posts.
- **Button: "Delete Asset"**: Safely deletes unreferenced media files.

---

## 📊 11. Financial Reports & Analytics (`/admin/reports`)

- **Analytical Overview**: Gross revenue, total order count, Average Order Value (AOV), and Mobile Money share percentage.
- **Date & Dimension Filters**: Filter by start date, end date, sales channel (`web` vs `pos`), payment method (`cash`, `momo`, `card`), and payment status.
- **Top 10 Bestselling Products**: Quantity and revenue breakdown for kitchen prep planning.
- **Daily Revenue Timeline**: Visual chart tracking 14-day or custom-window sales trajectories.
- **Button: "Export CSV"**: Streams an instantaneous UTF-8 BOM CSV spreadsheet containing full order breakdowns ready for Microsoft Excel or QuickBooks.

---

## 📣 12. Customer Broadcasts (`/admin/broadcast`)

- Compose marketing and operational announcements sent to registered patrons.
- **Target Audience Selector**: Choose between `All Customers`, `Active Buyers (Last 30 Days)`, or `Registered Accounts`.
- **Composer**: Email subject line, rich message body, and optional banner image.
- **Button: "Send Email Broadcast"**: Dispatches queued emails via Laravel's mail worker.

---

## 👥 13. User Accounts & Staff Administration (`/admin/users`)

- Roster of all administrative and staff profiles.
- **Button: "Create Staff Member"**: Assign name, work email, phone, and role (`super_admin`, `admin`, `manager`, `cashier`, `kitchen_staff`, `order_manager`, `content_manager`).
- **Button: "Toggle Active Status"**: Instantly grants or revokes system access.
- **Button: "Reset Password"**: Securely updates staff credentials with audit logging.

---

## ⚙️ 14. Modular Settings Console (`/admin/settings`)

Structured into 8 self-contained single-action cards to eliminate DOM form nesting:

1. **Card 1: Brand Identity & Dynamic Logo**: Site title, slogan, and brand logo uploader (`POST /admin/settings/logo`).
2. **Card 2: Production Hub & Store Address**: Physical address, landmark descriptions, and Google Maps embed code.
3. **Card 3: Direct Contacts & Desks**: Official phone lines, support email, and WhatsApp desk number.
4. **Card 4: Social Media Channels**: Links to Instagram, Facebook, TikTok, and X.
5. **Card 5: Fulfillment Controls & Logistics**: Flat delivery fee (`GH₵ 15.00`), minimum order spend, free delivery thresholds, and pickup times.
6. **Card 6: Financials, Currency & Tax Parameters**: Currency symbol (`GH₵`), ISO currency code (`GHS`), VAT rate, and receipt footer notes.
7. **Card 7: Payment API Gateways**: Paystack Public Key, Paystack Secret Key, and Mobile Money merchant codes.
8. **Card 8: Automated Customer Notifications**: Email switches, receipt message templates, and the **"Purge Application Cache"** button.

---

## 🔒 15. Immutable Audit Trail (`/admin/audit-logs`)

- Records all significant state mutations across the system.
- **Captured Data**: Event name, Operator user, Target model entity, Timestamp, Client IP address, and User-Agent.
- **Redaction Protocol**: Sensitive attributes (`password`, `token`, `secret`, `card`, `api_key`) are masked with `[REDACTED]`.
- **Button: "Inspect State"**: Launches modal displaying side-by-side JSON diffs of before and after state snapshots.

---

*For counter register workflows, consult the [POS Operations Guide](pos.md). For financial accounting details, refer to the [Accounts and Ledgers Guide](accounts.md).*