# 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
(Self-Service / Cart)"] + POS["Npontu-Style POS
(Counter Cashier / Barcode)"] + CATER["Catering Pipeline
(Weddings / Corporate)"] + INVP["Invoice Portal
(Yet-to-Pay / External)"] + end + + subgraph Gateways["Access & Privacy Control"] + SEC["Auth & Session Middleware"] + RBAC["Fine-Grained RBAC
(Role + Module Permissions)"] + DPC["Ghana Act 843 DPC Layer
(Consent & Data Rights)"] + end + + subgraph Core["Domain Business Services"] + ORDER["Order & Invoicing Engine
(OrderService / InvoiceController)"] + FULFILL["Fulfillment Manager
(Dine-In / Pickup / Delivery)"] + STOCK["Inventory Movement Ledger
(Atomic Decrement & Restock)"] + end + + subgraph Payments["Multi-Rail Settlement"] + PAYSTACK["Paystack Gateway
(MTN MoMo, Telecel, Card)"] + CASH["Cash Register
(Tender & Change Calculator)"] + OFFLINE["Manual MoMo Transfer
(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 1. **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. 2. **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`). 3. **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.). 4. **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.