> For the complete documentation index, see [llms.txt](https://docs.enicebakerygh.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enicebakerygh.com/architecture-and-engineering/architecture.md). # System Architecture & Multi-Channel ERP 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. ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.enicebakerygh.com/architecture-and-engineering/architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.