Architecture & Engineering Design

This document details the architectural boundaries, system layers, design patterns, and domain abstractions of the Eniceberny Bakery and Culinary Hub platform.

-## 1. System Layers +## 1. Multi-Channel ERP Architecture

-The platform follows a layered clean architecture with strict unidirectional flow: +Eniceberny acts as an end-to-end culinary Enterprise Resource Planning (ERP) engine, integrating in-store retail Point of Sale (POS), e-commerce digital ordering, corporate catering pipelines, and direct invoice settlements into a singular inventory and accounting ledger. + +```mermaid +flowchart TD

subgraph Channels["Ingestion Touchpoints"]

   WEB["Web Storefront<br/>(Self-Service / Cart)"]

   POS["Npontu-Style POS<br/>(Counter Cashier / Barcode)"]

   CATER["Catering Pipeline<br/>(Weddings / Corporate)"]

   INVP["Invoice Portal<br/>(Yet-to-Pay / External)"]

end
subgraph Gateways["Access & Privacy Control"]
```
   SEC["Auth & Session Middleware"]
```

   RBAC["Fine-Grained RBAC<br/>(Role + Module Permissions)"]

   DPC["Ghana Act 843 DPC Layer<br/>(Consent & Data Rights)"]

end
subgraph Core["Domain Business Services"]

   ORDER["Order & Invoicing Engine<br/>(OrderService / InvoiceController)"]

   FULFILL["Fulfillment Manager<br/>(Dine-In / Pickup / Delivery)"]

   STOCK["Inventory Movement Ledger<br/>(Atomic Decrement & Restock)"]

end
subgraph Payments["Multi-Rail Settlement"]

   PAYSTACK["Paystack Gateway<br/>(MTN MoMo, Telecel, Card)"]

   CASH["Cash Register<br/>(Tender & Change Calculator)"]

   OFFLINE["Manual MoMo Transfer<br/>(Reconciliation Ledger)"]

end
WEB --> SEC --> DPC --> ORDER
INVP --> SEC --> ORDER
POS --> RBAC --> ORDER
CATER --> RBAC --> ORDER
ORDER --> FULFILL
ORDER --> STOCK
ORDER --> Payments +```

+--- + +## 2. System Layers & Boundaries + +The platform follows a layered clean architecture with strict unidirectional flow:

┌────────────────────────────────────────────────────────┐
│                   Presentation Layer                   │
-│      Blade Views, Alpine.js, Tailwind v4, API Json     │
+│   Blade Views, Alpine.js, Tailwind CSS v4, API Json    │
└───────────────────────────┬────────────────────────────┘
                            │
┌───────────────────────────▼────────────────────────────┐
│                    Application Layer                   │
-│    Controllers, Form Requests, Policies, Middleware    │
+│  Controllers, Form Requests, Policies, RBAC Middleware │
└───────────────────────────┬────────────────────────────┘
                            │
┌───────────────────────────▼────────────────────────────┐
│                  Domain / Business Logic               │
-│ CartService, OrderService, PaymentManager, MediaManager│
+│ CartService, OrderService, InvoiceService, MediaManager│
└───────────────────────────┬────────────────────────────┘
                            │
┌───────────────────────────▼────────────────────────────┐
│                   Persistence Layer                    │
-│      Eloquent Models, Scopes, Relational Schemas       │
+│   Eloquent Models, Scopes, Casts, Relational Schemas   │
└───────────────────────────┬────────────────────────────┘
                            │
┌───────────────────────────▼────────────────────────────┐
│                 Infrastructure & Storage               │
-│   SQLite / PostgreSQL, Filesystem Driver (S3/R2/Local)  │
+│   PostgreSQL / SQLite, Paystack API, Local/S3 Storage  │
└────────────────────────────────────────────────────────┘

Layer Responsibilities

Presentation Layer:

- Customer Storefront & Cart Drawer (resources/views/storefront/*)
- Staff POS Counter Register (resources/views/admin/pos/*)

- Customer Storefront & Cart Drawer (resources/views/storefront/shop/*, checkout/*)
- Staff POS Counter Register with Npontu-inspired quick tender (resources/views/admin/pos/*)
- Public & Authenticated Invoices ("Yet to Pay") Portal (resources/views/storefront/invoices/*)
- Back-Office Administrative Dashboard (resources/views/admin/*)

- Internal API endpoints (/api/v1/*)
- Zero hardcoded business data or prices in Blade files; completely database-driven.

Application Layer:

- Dedicated HTTP controllers partitioned into Storefront\, Admin\, and Auth\.
- Strict input validation using Form Requests (CheckoutRequest, ProductRequest, CategoryRequest, CateringInquiryRequest).
- Authorization using AdminMiddleware ensuring non-admin users cannot access management consoles.

- Partitioned HTTP controllers: Storefront\, Admin\, and Auth\.
- Granular RBAC checks: canAccessSection($section) enforced per admin module.
- Strict input validation using Form Requests (CheckoutRequest, CateringInquiryRequest, ProductRequest).

Domain Layer:

- CartService: Session-isolated basket calculation, promotions application, tax computation.
- OrderService: Transactional order placement, immutable item snapshotting, status lifecycle dispatch.
- PaymentManager: Multi-gateway payment router (CashGateway, MobileMoneyGateway, PaystackGateway).
- MediaManager: Centralized file hashing, MIME validation, dimension extraction, storage key generation.
- SettingsManager: Centralized key-value site configurations with caching.

- OrderService: Transactional order creation, inventory deduction, status history logging.
- CartService: Session-isolated basket calculation, promotions, and VAT computation.
- PaymentManager: Paystack API integration for MoMo (MTN, Telecel, AT) and card charges.
- SettingsManager: Dynamic fulfillment toggles (order_delivery_enabled, order_pickup_enabled, order_dine_in_enabled, etc.).

Persistence Layer:

- Fully normalized relational schema with foreign key constraints, indexes, and soft deletions on auditable business records.
- Immutable historical records (order_items, order_status_histories, payment_transactions, inventory_movements, audit_logs).

- Fully normalized relational schema with foreign keys, compound indexes, and auditable immutable logs (order_items, order_status_histories, payment_transactions, inventory_movements).

-## 2. Key Domain Workflows +## 3. Order Lifecycle State Machine

-### 2.1 Order Lifecycle State Machine +Every order moves through a deterministic status lifecycle:

-``` -[Pending] ──> [Confirmed] ──> [Preparing / Kitchen] ──> [Out for Delivery / Ready for Pickup] ──> [Completed]

│ ▲
└───────────────────────────── [Cancelled] ────────────────────────────────────────────────────────┘ +```mermaid +stateDiagram-v2

[*] --> Pending: Created
Pending --> Confirmed: Paid (Paystack / Cash / MoMo)
Pending --> Cancelled: Expired or Cancelled
Confirmed --> Preparing: Kitchen Ticket Dispatched
Preparing --> ReadyForPickup: Takeaway / Pickup
Preparing --> OutForDelivery: Delivery Rider In Transit
Preparing --> Served: In-Store Dine-In
ReadyForPickup --> Completed: Handed to Customer
OutForDelivery --> Completed: Delivered with GhanaPost GPS
Served --> Completed: Table Session Closed
Cancelled --> [*]
Completed --> [*]


-- Statuses are formalized in `App\Enums\OrderStatus`.
-- Every transition appends a permanent record in `order_status_histories` tracking the actor and staff note.
+---

-### 2.2 Point of Sale (POS) Architecture
+## 4. Ghana Data Protection Act, 2012 (Act 843)

-Rather than maintaining a disconnected retail system, the staff POS counter (`/admin/pos`) reuses the core `Order`, `OrderItem`, `PaymentTransaction`, and `InventoryMovement` models with `'source' => 'pos'`.
-- Supports walk-in guest checkout or registered customer lookup.
-- Fast category switcher and keyboard/touch-friendly numeric steppers.
-- Real-time stock decrementing upon transaction completion.
-- One-click trigger for printable tax receipt.
-
----
-
-## 3. Technology Stack
-
-- **Backend**: Laravel 11.x on PHP 8.4
-- **Database**: SQLite (local development/tests), PostgreSQL 16 (Render production)
-- **Frontend**: Blade components, Alpine.js 3.x, Tailwind CSS v4 with brand OKLCH tokens
-- **Asset Pipeline**: Vite 6.x + Rolldown Windows native bindings
-- **Testing**: PHPUnit with SQLite in-memory refresh database
-
The platform strictly conforms to Act 843 principles overseen by the Data Protection Commission (DPC) Ghana:
1. **Accountability**: Designates a Data Protection Officer contact (`privacy@enicebakerygh.com`).
2. **Lawfulness of Processing**: Lawful ground established under Sections 18 (Consent), 19 (Contract Performance), and 20 (GRA Tax Compliance).
3. **Data Subject Rights**: Full customer self-service rights via `/account/settings` (Section 35 Access, Section 39 Rectification, Section 40 Erasure, and Section 41 Marketing Opt-out).
4. **Financial Data Security**: Zero credit card PAN/CVV or Mobile Money PINs are processed or stored on our servers; payments are tokenized via Bank of Ghana-licensed Paystack infrastructure.

---

## 5. Phase 4 Cinematic Landing Page & Visual Architecture

The public storefront follows an editorial, art-directed culinary layout designed for high emotional resonance and friction-free commercial conversion across desktop and mobile screens:

### 5.1 Presentation Topology
- **Cinematic Hero**: Rich ambient food video loop (`video.mp4` / high-res poster fallback) with dark gradient vignette, dynamic chef's signature pill, and direct dual CTAs (`/shop` and `/catering`).
- **Trust & Heritage Strip**: 4 core quality pillars directly bound to dynamic CMS settings (`home_val1_title` through `home_val4_title`).
- **Curated Category Grid**: 5 departments (Continental Dishes, Local Ghanaian Cuisine, Pastries & Cakes, Fresh Drinks & Juices, Food Baskets & Platters) dynamically populated from active database records.
- **Editorial Spotlight**: Masterpiece feature card beside companion stacked culinary rows with real pricing and direct ordering links.
- **Dedicated Ghanaian Flavour Section**: "Rooted in Ghana. Made for Every Table." celebrating Fufu, Banku, Emotuo, and Abete3.
- **Bespoke Cake Studio & Executive Catering**: Comprehensive event planning pathways supporting up to 500 guests.
- **Interactive Visual Gallery**: Masonry gallery with full-screen interactive Alpine.js Lightbox Modal supporting keyboard navigation and Esc key listener.
- **Mobile Auth Ergonomics**: Standalone top action bar with prominent "← Back to Storefront" navigation and isolated guest containers eliminating mobile overscroll clashes.

GitBook Docs AI Assistant

Architecture & Engineering Design

Layer Responsibilities

Your Bakery Basket

Your basket is empty