Ecommerce
Portal Manual

1. Project Overview

1.1 Project Introduction

Selfimart Ecommerce is a comprehensive, enterprise-grade ecommerce platform designed to bridge the gap between traditional brick-and-mortar retail experiences and modern online shopping. The platform is built with a focus on multi-stakeholder interactions, enabling various user roles — including sellers, resellers, store agents, delivery personnel, and buyers — to interact seamlessly within a unified ecosystem.

The platform encompasses several innovative features that distinguish it from conventional ecommerce solutions, making it a unique solution for modern retail operations that require both online and offline capabilities. At its core, Selfimart is designed to serve as a complete commerce infrastructure: from product listing and inventory management to order fulfillment, commission tracking, and real-time delivery monitoring.

1.2 Core Platform Features

Multi-Role Ecosystem The system supports ten distinct user roles, each with specific permissions and capabilities that define their interaction with the platform. This granular role management ensures that every stakeholder has access to the appropriate tools and data necessary for their specific function within the ecommerce ecosystem. Role-based access control is enforced at every level — from dashboard navigation to API endpoints.

Physical-Digital Integration (Scan & Go) One of the most innovative aspects of Selfimart is its "Scan & Go" self-checkout system. This feature allows customers in physical stores to scan QR codes placed on products, add items to a virtual cart, and complete payments directly from their mobile devices. The successful payment triggers an automatic inventory sync, bridging the gap between offline and online retail experiences. This Progressive Web App (PWA) operates without requiring account registration, making it accessible to all in-store customers.

Comprehensive Commission System The platform implements a sophisticated commission structure that tracks earnings for sellers, resellers, delivery personnel, and store agents. The commission logic operates on a profit-based calculation rather than total product value. Sellers earn commissions from their product sales while contributing a percentage to the platform, whereas resellers earn commissions from the platform based on products they promote and sell through their unique referral codes. Commission policies are fully configurable by administrators.

Real-Time Delivery Tracking Integration with Google Maps API and WhatsApp Business API enables real-time delivery tracking. Buyers can monitor their deliveries live through GPS coordinate tracking and WhatsApp geolocalization, while sellers, resellers, and administrators can also track the progress of products associated with their accounts. Delivery personnel update their location in real time, providing full transparency throughout the fulfillment chain.

Multi-Branch Inventory Management The system supports multiple store branches with comprehensive inventory management capabilities, including stock transfers between branches, low-stock alerts, and real-time inventory updates. Each branch maintains its own inventory records while being connected to the central system for unified management and reporting. The self-checkout system integrates directly with branch inventory for automatic stock deduction upon payment.

Global Currency Support With Kenyan Shillings (KES) as the default currency, the platform supports multi-currency transactions with automatic exchange rate updates, making it suitable for international commerce. Customers can view prices in their preferred currency while all internal calculations remain anchored to KES.

1.3 Key Business Objectives

The Selfimart Ecommerce platform is designed to achieve several strategic business objectives that align with modern retail demands:

• Revenue Generation: Multiple revenue streams including direct sales, seller commissions, reseller commissions, and delivery fees ensure sustainable platform income.
• Market Expansion: Reseller tools expand market reach via unique referral codes and social selling capabilities, creating a self-sustaining network of product promoters.
• Operational Efficiency: Automating order processing, inventory management, delivery assignment, and commission calculations reduces manual overhead and human error.
• Customer Experience: Seamless shopping experiences across both online platforms and physical store locations ensure high customer satisfaction and repeat purchases.
• Scalability: The system architecture is designed to handle growth in products, users, and transactions without performance degradation, supporting the platform's long-term expansion.

1.4 Integration Requirements

The platform integrates with several external services to deliver its full feature set:

• Google Maps API — Real-time delivery tracking and geographic coordinate management for picking points.
• WhatsApp Business API — Live delivery tracking links and customer notifications via WhatsApp.
• Stripe — International card payment processing with full PCI compliance.
• Paystack — African payment gateway supporting card and mobile money payments.
• MTN MoMo — Mobile money payment integration for East and Central Africa.
• Pesapal — Multi-payment aggregator supporting M-Pesa, cards, and bank transfers.
• Africa's Talking — SMS gateway for OTP delivery, order notifications, and bulk messaging.
• Google OAuth / Facebook OAuth — Social authentication for simplified user registration and login.
• AWS S3 / SFTP / FTP — Cloud and remote file storage for media assets and backups.

---

2. Technology Stack and Dependencies

2.1 Core Technology Overview

The Selfimart Ecommerce platform is built on a modern, robust technology stack designed for performance, scalability, and maintainability. Each layer of the stack has been carefully selected to ensure seamless integration and optimal performance across all components of the system.

Layer	Technology	Version	Responsibility
Backend	Laravel	12.x	Routing, Authentication, API, Business Logic
Database	MySQL	5.7+	Relational data storage and query optimization
Frontend	Blade + Alpine.js	Latest	Server-side rendering with client-side interactivity
Styling	Tailwind CSS	4.x	Utility-first responsive design system
Security	Spatie Laravel-Permission	Latest	Role-Based Access Control (RBAC)
API Auth	Laravel Sanctum	Latest	Token-based API authentication
Build Tool	Vite	5.x	Frontend asset bundling and hot module replacement
Queue	Laravel Queues + Redis	Latest	Background job processing and caching

2.2 Backend Dependencies (composer.json)

Core Framework Dependencies:

Package	Version	Purpose
laravel/framework	^12.0	Core PHP framework providing routing, ORM, authentication, and MVC architecture
laravel/sanctum	^4.0	Token-based API authentication for mobile apps and external integrations
laravel/socialite	^5.14	Social authentication (Google, Facebook OAuth) for simplified user registration
laravel/tinker	^2.10	Interactive REPL for debugging and testing in development environments

Security and Permissions:

Package	Version	Purpose
spatie/laravel-permission	^6.10	Role-based access control with roles, permissions, and direct assignment to models
spatie/laravel-activitylog	^4.8	Comprehensive audit trail logging for all user activities and model changes
spatie/laravel-medialibrary	^11.8	File and image management with automatic conversions and optimizations
spatie/laravel-sluggable	^3.7	Automatic slug generation for SEO-friendly URLs on products and pages
spatie/laravel-backup	^8.8	Automated database and file backup scheduling with cloud storage support

Data Processing and Export:

Package	Version	Purpose
barryvdh/laravel-dompdf	^2.0	PDF generation for invoices, receipts, reports, and this manual
maatwebsite/excel	^3.1	Excel import/export for bulk product uploads, order exports, and reporting
intervention/image	^3.4	Image manipulation, resizing, watermarking, and optimization
simplesoftwareio/simple-qrcode	^4.2	QR code generation for products and self-checkout sessions

Payment and Communication:

Package	Version	Purpose
stripe/stripe-php	^13.0	Stripe payment gateway integration for international card payments
africastalking/africastalking	^3.0	SMS notifications, OTP delivery, and bulk messaging via Africa's Talking

Data Visualization and Tables:

Package	Version	Purpose
consoletvs/charts	^7.0	Interactive charts and graphs for dashboard analytics and reporting
yajra/laravel-datatables-oracle	^10.11	Server-side DataTables processing for large datasets with search and pagination

File Storage:

Package	Version	Purpose
league/flysystem-aws-s3-v3	^3.0	AWS S3 cloud storage integration for media assets and backups
league/flysystem-sftp-v3	^3.0	SFTP remote file storage support
league/flysystem-ftp	^3.0	FTP file storage support for legacy integrations

2.3 Frontend Dependencies (package.json)

Development Dependencies:

Package	Version	Purpose
tailwindcss	^4.0.0	Utility-first CSS framework for rapid, consistent UI development
@tailwindcss/vite	^4.0.0	Vite plugin for Tailwind CSS processing and optimization
@tailwindcss/forms	^0.5.7	Form styling utilities for consistent, accessible form appearance
@tailwindcss/typography	^0.5.10	Typography plugins for prose content styling in CMS pages
alpinejs	^3.13.10	Lightweight JavaScript framework for client-side interactivity without a full SPA
vite	^5.4.0	Next-generation frontend build tool with hot module replacement
laravel-vite-plugin	^1.0.2	Official Laravel integration for Vite asset bundling
axios	^1.6.7	Promise-based HTTP client for API requests and AJAX operations

Production Dependencies:

Package	Version	Purpose
@fortawesome/fontawesome-free	^6.5.1	Comprehensive icon library for all UI elements and navigation
chart.js	^4.4.2	JavaScript charting library for dashboard analytics and reports
datatables.net	^2.0.3	jQuery DataTables for interactive tabular data with sorting and filtering
choices.js	^10.2.0	Enhanced select dropdowns with search, multi-select, and custom styling
flatpickr	^4.6.13	Lightweight date and time picker component for forms
sweetalert2	^11.10.5	Beautiful, accessible alert and confirmation dialogs
swiper	^11.0.7	Touch-enabled slider for product image carousels and promotional banners
quill	^2.0.2	Rich text editor for content management and product descriptions
nprogress	^0.2.0	Slim progress bars for page loading feedback

---

3. Role Overview

The Selfimart platform implements a comprehensive role-based access control system with ten distinct user roles. Each role is designed to fulfill specific business functions within the ecommerce ecosystem, ensuring appropriate access levels and capabilities for every type of user. Roles are managed through Spatie Laravel-Permission and enforced at both the middleware and policy levels.

3.1 Super Admin

The Super Admin role represents the platform owner with complete, unrestricted control over all system aspects. This role has access to every module, sub-module, and configuration setting within the platform. Super Admins can manage all users across all roles, create and assign roles, configure system-wide settings, process payments and refunds, view all audit trails, manage external integrations, and override any system constraint.

This role is typically assigned to the business owner or highest-level management personnel who require full visibility and control over the entire platform operation. There should be only one or very few Super Admin accounts to minimize security risk.

Key Capabilities: Full user management, all module access, system configuration, financial oversight, audit trail access, integration management, role and permission management.

3.2 Admin

The Admin role provides comprehensive platform administration capabilities for day-to-day operations management. Administrators can manage products, orders, users (with some limitations), view reports, handle customer support escalations, and configure most system settings. However, they cannot modify Super Admin accounts, change core system configurations, or access certain sensitive audit information.

This role is suitable for operations managers, product managers, and customer service supervisors who need comprehensive access without full system control. Multiple Admin accounts can be created for different operational departments.

Key Capabilities: Product management, order processing, user management (non-super-admin), report viewing, customer support, most configuration settings.

3.3 Seller

Sellers are third-party product vendors who upload and manage their own products on the platform. They earn commissions from their product sales after platform fees are deducted. Sellers can create product listings with full details and image galleries, manage inventory for their products, view sales reports and analytics, track commission earnings, and respond to product reviews.

Sellers can also function as resellers for other sellers' products, creating additional revenue streams beyond their own catalog. This role is ideal for manufacturers, distributors, and independent vendors who want to sell through the Selfimart marketplace.

Key Capabilities: Product creation and management, inventory tracking, sales reporting, commission tracking, review responses, reseller code generation for other products.

3.4 Reseller

Resellers are product promoters who generate unique referral codes for existing products and earn commissions on successful sales made through their codes. They cannot upload products themselves but can browse all available products for reselling, set their own prices within admin-defined minimum and maximum ranges, generate and share unique product codes across social media and other channels, track clicks and conversions, and view their commission earnings.

This role creates a powerful network effect where multiple participants actively promote products, expanding market reach without requiring inventory investment. Resellers are particularly effective for social commerce and influencer marketing.

Key Capabilities: Browse available products, generate unique reseller codes, set prices within allowed ranges, share codes, track conversions, view commission earnings.

3.5 Store Agent

Store Agents operate as both sellers and resellers for specific branch locations. They represent a physical store branch and have the combined capabilities of both the Seller and Reseller roles. They can upload products for their branch, manage branch inventory, generate reseller codes, handle local customer relations, and earn both seller and reseller commissions.

This role is essential for multi-branch retail operations where each location needs dedicated management with full local control. Store Agents are also the primary operators of the self-checkout system within their branch.

Key Capabilities: All Seller capabilities for their branch, all Reseller capabilities, branch inventory management, self-checkout oversight, local customer support.

3.6 Developer

Developers are technical integrators who manage API access and external integrations. They can create and manage API keys, access comprehensive API documentation, configure webhooks, view integration logs, generate SDKs for multiple programming languages, and manage ERP connection settings.

This role is crucial for businesses that need to connect external ERP systems, mobile applications, or third-party services to the Selfimart platform. Developers also have access to the full audit trail for debugging and integration troubleshooting.

Key Capabilities: API key management, API documentation access, webhook configuration, integration log viewing, SDK generation, ERP integration management, audit trail access.

3.7 Delivery Personnel

Delivery Personnel are logistics handlers responsible for order fulfillment and product transportation. They can view their assigned deliveries, update delivery status and GPS location in real time, capture proof of delivery (photos and signatures), communicate with customers, and track their delivery fee earnings.

This role integrates directly with the Google Maps tracking system to provide live delivery updates to buyers and administrators. Delivery personnel use a dedicated mobile-optimized dashboard for efficient on-the-road operations.

Key Capabilities: View assigned deliveries, update delivery status, GPS location updates, proof of delivery capture, customer communication, delivery fee tracking.

3.8 Buyer

Buyers are end customers who browse, purchase, and review products. They can search and browse the full product catalog, add items to cart and wishlist, complete checkout with various payment methods, track order status and delivery in real time, write product reviews, manage multiple shipping addresses, and view their complete purchase history.

This is the most common user type and forms the foundation of the platform's customer base. Buyer accounts can be created instantly without administrative approval, enabling frictionless onboarding.

Key Capabilities: Product browsing and search, cart and wishlist management, multi-method checkout, order and delivery tracking, product reviews, shipping address management, purchase history.

3.9 Chat Agent

Chat Agents provide customer support through live chat interactions. They can handle incoming chat sessions assigned to their department, view customer order history for context-aware support, escalate complex issues to support tickets, transfer chats to other available agents, and set their availability status.

This role requires a chat-agent detail record with department assignment and maximum concurrent chat configuration. Chat Agents operate from a dedicated support dashboard with real-time chat notifications.

Key Capabilities: Handle live chat sessions, view customer order history, create and manage support tickets, transfer chats, set availability status, view chat history.

3.10 Marketer

Marketers manage promotional content and marketing communications across the platform. They can create and manage website pages, design and send newsletters, manage FAQs and product news articles, configure product sliders and highlight assignments, and view marketing analytics including newsletter open rates and click-through rates.

This role is essential for content marketing and customer engagement activities. Marketers work within the Content Management and Communication modules to drive traffic and conversions.

Key Capabilities: Page creation and management, newsletter campaigns, FAQ management, product news, slider configuration, product highlight management, marketing analytics.

---

4. Testing User Login Credentials

The following test accounts are pre-configured for system testing and demonstration. All passwords are set to password123. These accounts represent all ten roles with role-specific detail records fully configured.

Security Note: These credentials are for testing purposes only. Change all passwords before deploying to a production environment.

4.1 Super Admin Account

Name	Email	Password	Phone
John Kamau	superadmin@selfimart.com	password123	+254701000001

4.2 Admin Accounts

Name	Email	Password	Phone
Mary Wanjiku	admin@selfimart.com	password123	+254701000002
Peter Mwangi	admin2@selfimart.com	password123	+254701000003

4.3 Seller Accounts

Name	Email	Password	Phone	Business Name
James Ochieng	seller1@selfimart.com	password123	+254701000010	TechHub Kenya
Grace Njeri	seller2@selfimart.com	password123	+254701000011	Fashion House KE
Daniel Kipchoge	seller3@selfimart.com	password123	+254701000012	Home Essentials Ltd

4.4 Reseller Accounts

Name	Email	Password	Phone	Region
Lucy Muthoni	reseller1@selfimart.com	password123	+254701000020	Nairobi
Samuel Njoroge	reseller2@selfimart.com	password123	+254701000021	Mombasa
Faith Wambui	reseller3@selfimart.com	password123	+254701000022	Kisumu

4.5 Store Agent Accounts

Name	Email	Password	Phone
Michael Otieno	storeagent1@selfimart.com	password123	+254701000030
Anne Nyambura	storeagent2@selfimart.com	password123	+254701000031

4.6 Developer Account

Name	Email	Password	Phone
Brian Kipruto	developer@selfimart.com	password123	+254701000040

4.7 Delivery Personnel Accounts

Name	Email	Password	Phone	Vehicle
Joseph Mutua	delivery1@selfimart.com	password123	+254701000050	Motorcycle (KMD 123A)
Esther Achieng	delivery2@selfimart.com	password123	+254701000051	Van (KBZ 456B)
David Waweru	delivery3@selfimart.com	password123	+254701000052	Motorcycle (KME 789C)

4.8 Buyer Accounts

Name	Email	Password	Phone
Catherine Njoki	buyer1@selfimart.com	password123	+254701000060
Robert Kipkemoi	buyer2@selfimart.com	password123	+254701000061
Jennifer Atieno	buyer3@selfimart.com	password123	+254701000062
Christopher Musyoka	buyer4@selfimart.com	password123	+254701000063
Patricia Wairimu	buyer5@selfimart.com	password123	+254701000064

4.9 Chat Agent Accounts

Name	Email	Password	Phone
Agnes Wambui	chatagent1@selfimart.com	password123	+254701000070
Francis Mwiti	chatagent2@selfimart.com	password123	+254701000071

4.10 Marketer Accounts

Name	Email	Password	Phone
Veronica Mwende	marketer1@selfimart.com	password123	+254701000080
Thomas Kariuki	marketer2@selfimart.com	password123	+254701000081

---

5. Modules and Sub-Modules

The Selfimart platform is organized into 19 functional modules, each addressing a specific domain of the ecommerce operation. Every module contains one or more sub-modules accessible from the dashboard sidebar. The following sections provide a comprehensive guide to each module including its purpose, sub-modules, role permissions, and step-by-step usage instructions.

---

5.1 User Management Module

Module Overview

The User Management Module serves as the foundation for all user-related operations within the Selfimart platform. This module handles user registration, authentication, role assignment, and profile management across all ten user roles. It ensures that every stakeholder has appropriate access levels and can perform their designated functions within the system.

Module Business Purpose

The primary business purpose of this module is to maintain a secure, organized user base with clear role distinctions and appropriate access controls. It enables the platform to manage the complex multi-stakeholder ecosystem where sellers, resellers, buyers, and operational staff coexist with distinct permissions and capabilities. The module supports the approval workflow for roles requiring administrative vetting while enabling instant access for standard buyer accounts.

Sub-Modules

• 5.1.1 Users: Manages core user accounts including creation, editing, deletion, and status management. Provides user listing with server-side DataTables, CSV/Excel export capabilities, and bulk status operations. Displays role-specific detail information alongside core user data.
• 5.1.2 User Roles: Handles role definitions and assignments. Includes role CRUD operations, role-based permission grouping, and role description management. Roles are synchronized with Spatie Laravel-Permission for consistent enforcement.
• 5.1.3 Role Permissions: Manages granular permissions and their assignment to roles. Includes a visual permission matrix for bulk permission updates across all roles simultaneously. Permissions are organized by module for clarity.
• 5.1.4 User Manager: Provides role-specific registration forms with dynamic field loading based on selected role. Handles user type management, approval workflows for sensitive roles, and rejection with reason tracking.

Role Permissions Matrix

Role	View Users	Create Users	Edit Users	Delete Users	Manage Roles
Super Admin	All	All	All	All	Full
Admin	All	—	—	—	View Only
All Others	Own Profile	—	Own Profile	—	—

Step-by-Step Execution

1. Access User Management: Navigate to Dashboard → User Management → Users
2. Create New User: Click "Create User", fill required fields (name, email, phone, password), select role, complete role-specific fields, submit form
3. Edit User: Click the user row or edit icon, modify fields as needed, save changes
4. Manage Roles: Navigate to User Roles, click "Create Role" or edit existing role, define role name and description
5. Assign Permissions: Navigate to Role Permissions, select a role from the matrix, toggle permissions on/off, save the permission set
6. Approve Pending Users: Navigate to User Manager → Pending Approvals, review application details, click Approve or Reject with reason

Security Measures

• Password hashing using bcrypt with cost factor 12
• Email verification required before account activation
• Approval workflow for sensitive roles (Seller, Reseller, Store Agent, Developer, Delivery Personnel)
• Comprehensive audit logging of all user management actions
• CSRF protection on all forms
• Rate limiting on authentication and registration endpoints

Dashboard Sidebar Path: User Management → Users / User Roles / Role Permissions / User Manager

---

5.2 Configuration Module

Module Overview

The Configuration Module centralizes all system-wide settings including SMS provider credentials, email server settings, payment gateway configurations, and social authentication credentials. This module enables administrators to configure external service integrations through a user-friendly interface without modifying code files or environment variables directly.

Module Business Purpose

The business purpose is to provide a single point of configuration for all external service integrations, enabling quick setup and modification of SMS providers, email services, payment gateways, and social login options. This reduces dependency on technical staff for routine configuration changes and enables rapid response to service provider changes or credential rotations.

Sub-Modules

• 5.2.1 SMS Configuration: Manages Africa's Talking SMS provider settings including API key, username, sender ID, and test messaging capabilities. Supports sending test SMS to verify configuration.
• 5.2.2 Payment Configuration: Configures payment gateway credentials for Stripe (publishable and secret keys), Paystack (public and secret keys), MTN MoMo (API user, API key, subscription key), and Pesapal (consumer key and secret). Each gateway can be individually enabled or disabled.
• 5.2.3 Email Configuration: Manages SMTP settings including host, port, username, password, encryption type, and sender name/address. Supports testing email delivery through the configuration interface.
• 5.2.4 Social Authentication: Configures Google OAuth (client ID and secret, redirect URI) and Facebook OAuth (app ID and secret, redirect URI) credentials for social login functionality.

Role Permissions

Role	View	Edit	Test
Super Admin	✓	✓	✓
Admin	✓	—	✓
All Others	—	—	—

Dashboard Sidebar Path: Configurations → SMS / Payment / Email / Google Auth / Facebook Auth

---

5.3 Currency Management Module

Module Overview

The Currency Management Module handles multi-currency support for the Selfimart platform. With Kenyan Shillings (KES) as the default base currency, this module manages currency configurations, exchange rates, and display settings, enabling international customers to view prices in their preferred currency throughout the shopping experience.

Module Business Purpose

This module enables global commerce by allowing customers to view and transact in their preferred currency while maintaining KES as the base currency for all internal calculations and reporting. It supports automatic exchange rate updates via scheduled commands and provides consistent currency formatting throughout the platform, including the correct symbol, decimal places, and thousands separator for each currency.

Sub-Modules

• 5.3.1 Currencies: Manages supported currencies including their ISO code, symbol, name, decimal places, formatting preferences (symbol position, thousands separator), and active/inactive status. The default currency (KES) cannot be deactivated.
• 5.3.2 Exchange Rates: Handles exchange rate management including manual rate entry, history tracking with timestamps, and automatic update scheduling via the UpdateExchangeRates artisan command. Rates are stored as multipliers relative to KES.

Role Permissions

Role	View	Create	Edit	Delete
Super Admin	✓	✓	✓	✓
Admin	✓	✓	✓	—
All Others	View Only	—	—	—

Dashboard Sidebar Path: Currency Management → Currencies / Exchange Rates

---

5.4 Theme Module

Module Overview

The Theme Module manages the visual appearance of the Selfimart platform, including color schemes, typography preferences, and layout configurations. The module supports dynamic theme switching and custom CSS injection for advanced customization without requiring code deployments.

Module Business Purpose

This module enables platform administrators to customize the visual identity of the ecommerce site to align with brand guidelines without requiring developer involvement. It supports seasonal theme changes for promotional periods, brand color updates, and typography adjustments. Theme changes take effect immediately across the entire platform.

Features

• Primary and secondary color configuration with hex color picker
• Font family selection for headings and body text
• Logo and favicon upload and management
• Custom CSS injection for advanced styling overrides
• Theme preview before applying changes
• Theme history with rollback capability

Role Permissions

Role	View	Edit
Super Admin	✓	✓
Admin	✓	—
All Others	—	—

Dashboard Sidebar Path: Theme (Direct Link)

---

5.5 Communication Module

Module Overview

The Communication Module handles all messaging capabilities within the Selfimart platform, including SMS campaigns, email marketing, live customer chat, support ticket management, and newsletter subscriptions. This module integrates with the Configuration Module's settings to dispatch messages through the configured providers.

Module Business Purpose

The module provides comprehensive communication channels for customer engagement, order notifications, marketing campaigns, and customer support. It centralizes all messaging operations and provides complete audit trails for compliance and quality assurance. All outbound communications are logged with delivery status for accountability.

Sub-Modules

• 5.5.1 SMS: Manages SMS templates with variable substitution, individual and bulk message composition, and complete sending history with delivery status tracking. Integrates with Africa's Talking for delivery.
• 5.5.2 Email: Handles email template management with rich HTML editing via Quill, campaign composition with recipient selection, scheduled sending, and delivery tracking with open and click rates.
• 5.5.3 Chat: Provides a real-time live chat interface for customer support with agent assignment, session management, typing indicators, file sharing, and chat history. Integrates with Laravel Echo and Pusher for real-time communication.
• 5.5.4 Tickets: Manages support tickets with category assignment, priority levels (low, medium, high, urgent), status tracking (open, in-progress, resolved, closed), internal notes, and customer-facing replies.
• 5.5.5 Newsletter: Handles newsletter campaign creation, subscriber list management, subscription/unsubscription processing, campaign scheduling, and engagement analytics including open rates and click-through rates.

Role Permissions

Role	SMS	Email	Chat	Tickets	Newsletter
Super Admin	Full	Full	Full	Full	Full
Admin	Full	Full	Full	Full	Full
Marketer	View	Full	—	—	Full
Chat Agent	—	—	Assigned Sessions	Assigned Tickets	—

Dashboard Sidebar Path: Communication → SMS / Email / Chat / Tickets / Newsletter

---

5.6 Store Management Module

Module Overview

The Store Management Module handles store owner details, branch management, inventory tracking, and stock transfers between branches. This module is essential for multi-location retail operations and provides comprehensive inventory visibility across all physical locations.

Module Business Purpose

The module provides centralized management of physical store locations and their inventory. It enables efficient stock transfers between branches with an approval workflow, configures low-stock alert thresholds, and provides real-time inventory updates that integrate directly with the self-checkout system. Branch-level reporting gives store managers visibility into their specific location's performance.

Sub-Modules

• 5.6.1 Store Owner: Manages store owner details including business name, registration number, contact information, and business address. Links the store owner to the platform's user account.
• 5.6.2 Branches: Handles store branch creation, editing, and status management. Each branch has a name, address, GPS coordinates, contact details, and operating hours. Branches are linked to Store Agent accounts.
• 5.6.3 Inventory: Provides real-time inventory tracking per branch with stock quantity, reserved quantity, and available quantity. Supports manual stock adjustments with reason logging and configurable low-stock alert thresholds.
• 5.6.4 Stock Transfers: Manages stock movement requests between branches with a two-step approval workflow. Transfer requests include product, quantity, source branch, destination branch, and transfer reason. Approved transfers automatically update inventory levels at both branches.

Role Permissions

Role	View	Create	Edit	Delete
Super Admin	All Branches	✓	All	✓
Admin	All Branches	✓	All	—
Store Agent	Own Branch	Own Branch	Own Branch	—

Dashboard Sidebar Path: Store Management → Store Owner / Branches / Inventory / Stock Transfers

---

5.7 Product Management Module

Module Overview

The Product Management Module is the core catalog module for managing all aspects of the product database, including products, categories, subcategories, brands, QR codes, tax settings, product highlights, and customer reviews. This module handles all product-related operations from initial creation through display on the public-facing website.

Module Business Purpose

This module enables comprehensive product catalog management with rich product information, multiple image galleries, detailed specifications, and real-time inventory tracking. It supports the complex product relationships required for a multi-seller ecommerce platform and integrates with all other modules that reference products — including orders, commissions, wishlists, and the self-checkout system.

Sub-Modules

• 5.7.1 Products: Full CRUD operations for products including name, SKU, description, specifications, multiple images (with primary image selection), pricing (regular and offer price), stock quantity, weight, dimensions, category, subcategory, brand, tax category, and special handling flags. Supports product status management (active, inactive, draft).
• 5.7.2 Categories: Manages the top-level product category hierarchy with name, slug, description, image, and featured status. Featured categories appear prominently on the homepage and navigation mega menu.
• 5.7.3 Subcategories: Manages subcategories nested under parent categories with name, slug, description, and image. Products are assigned to both a category and subcategory for precise catalog organization.
• 5.7.4 Brands: Handles brand management with brand name, slug, logo upload, description, and website URL. Products are linked to brands for brand-filtered browsing on the public site.
• 5.7.5 QR Codes: Generates and manages QR codes for individual products. QR codes are used in the self-checkout system — scanning a product QR code adds it to the customer's virtual cart in the PWA.
• 5.7.6 Tax Management: Configures tax categories (e.g., Standard Rate, Zero Rate, Exempt) and their associated tax rates as percentages. Products are assigned to tax categories for automatic tax calculation at checkout.
• 5.7.7 Highlights: Manages product highlight assignments including New Arrival, Featured, On Offer, and Best Seller. Highlighted products appear in dedicated sections on the homepage and can be filtered in the product catalog.
• 5.7.8 Reviews: Handles product review moderation including viewing submitted reviews, approving or rejecting reviews before publication, and managing seller responses to reviews. Review analytics show average ratings and review counts per product.
• 5.7.9 Wishlists: Provides wishlist analytics and management for administrators, including which products are most wishlisted, conversion rates from wishlist to purchase, and the ability to view all wishlists across the platform.

Role Permissions

Role	View	Create	Edit	Delete
Super Admin	All Products	✓	All	✓
Admin	All Products	✓	All	✓
Seller	Own Products	✓	Own	Own
Store Agent	Branch Products	✓	Branch	Branch

Dashboard Sidebar Path: Product Management → Products / Categories / Subcategories / Brands / QR Codes / Tax / Highlights / Reviews / Wishlists

---

5.8 Wishlist Module

Module Overview

The Wishlist Module provides buyers with the ability to save products for future purchase consideration. Products can be added to a wishlist from the product catalog or product detail page without adding them to the cart. This module also serves as a valuable analytics tool for understanding buyer interests and purchase intent patterns.

Module Business Purpose

The module enhances the shopping experience by allowing customers to curate personal product collections for future reference. It provides valuable analytics for sellers and administrators to understand product desirability, identify high-demand items, and measure conversion rates from wishlist to actual purchase. Price drop notifications on wishlisted items drive re-engagement and conversions.

Features

• Add and remove products from personal wishlist with a single click
• Public wishlist sharing via unique shareable link
• Move individual items or entire wishlist to cart
• Price drop notifications when wishlisted product prices decrease
• Wishlist analytics dashboard for administrators showing most-wishlisted products
• Wishlist count display on product cards for social proof

Role Permissions

Role	View	Add	Remove	Share	Analytics
Buyer	Own	✓	✓	✓	Own
Super Admin	All	—	—	—	All
Admin	All	—	—	—	All
Seller	Own Products	—	—	—	Own Products

---

5.9 Purchase Module

Module Overview

The Purchase Module manages the complete buyer journey from shopping cart through payment processing to order creation and delivery tracking. This module handles all shopping cart operations, payment gateway integrations, purchase history records, and delivery status visibility from the buyer's perspective.

Module Business Purpose

This module provides the complete shopping cart and checkout experience for buyers. It manages cart persistence across sessions and devices, promotional code application with discount calculation, shipping cost estimation based on selected delivery method, secure payment processing through multiple gateways, and comprehensive order history tracking with reorder capabilities.

Sub-Modules

• 5.9.1 Purchases: Displays the buyer's complete order history with current status, order total, item count, and tracking information. Supports filtering by status and date range, and provides one-click reorder functionality.
• 5.9.2 Cart: Manages the shopping cart with add, remove, and quantity update operations. Displays real-time subtotal, applicable discounts, estimated shipping, and tax. Supports promotional code application and cart sharing.
• 5.9.3 Payments: Handles payment processing through all configured gateways (Stripe, Paystack, MTN MoMo, Pesapal). Displays payment history with transaction IDs, amounts, gateway used, and payment status.
• 5.9.4 History: Maintains comprehensive purchase transaction records including payment receipts, invoice downloads, and refund tracking. Provides exportable purchase history for accounting purposes.
• 5.9.5 Deliveries: Provides delivery tracking from the buyer's perspective including current delivery status, assigned delivery personnel details, real-time GPS tracking link, and estimated delivery time.

Role Permissions

Role	View	Checkout	Payment
Buyer	Own	✓	Own
Super Admin	All	✓	All
Admin	All	✓	All

Dashboard Sidebar Path: Purchase Module → Purchases / Cart / Payments / History / Deliveries

---

5.10 Order Management Module

Module Overview

The Order Management Module handles all order processing operations including order viewing, status updates, delivery assignment, and order cancellation. This module serves as the central hub connecting buyers, sellers, and delivery personnel in the order fulfillment workflow.

Module Business Purpose

The module provides comprehensive order management capabilities for administrators, sellers, and support staff. It enables efficient order processing with clear status progression, streamlined delivery assignment, and effective issue resolution throughout the order lifecycle. Real-time order status updates keep all stakeholders informed at every stage.

Sub-Modules

• 5.10.1 All Orders: Complete order listing with advanced filtering by status, date range, seller, buyer, and payment method. Supports bulk status updates and CSV/Excel export for reporting.
• 5.10.2 Pending Orders: Orders awaiting processing or payment confirmation. Administrators can confirm payment, assign to processing, or cancel pending orders.
• 5.10.3 In Progress: Orders currently being processed, packed, or in transit. Shows processing timeline and allows delivery personnel assignment.
• 5.10.4 Delivered: Successfully completed orders with delivery confirmation details, proof of delivery images, and customer satisfaction ratings.
• 5.10.5 Declined: Cancelled or failed orders with cancellation reason, refund status, and resolution notes.

Role Permissions

Role	View	Update Status	Cancel	Assign Delivery
Super Admin	All	All	All	✓
Admin	All	All	All	✓
Seller	Own Products	Own	—	—
Buyer	Own	—	Own (Pending Only)	—

Dashboard Sidebar Path: Order Management → All Orders / Pending / In Progress / Delivered / Declined

---

5.11 Delivery Management Module

Module Overview

The Delivery Management Module manages all delivery operations including delivery personnel assignment, real-time route tracking, status updates, and proof of delivery capture. This module integrates with Google Maps API for live GPS tracking and WhatsApp Business API for customer delivery notifications.

Module Business Purpose

The module provides end-to-end delivery management from order dispatch to customer confirmation. It enables real-time tracking visible to buyers, sellers, and administrators, efficient delivery personnel assignment based on availability and location, and comprehensive delivery analytics for performance monitoring. The proof of delivery system ensures accountability and reduces disputes.

Sub-Modules

• 5.11.1 All Deliveries: Complete delivery listing with status, assigned personnel, tracking information, and delivery timeline. Supports filtering by status, date, delivery personnel, and branch.
• 5.11.2 Pending: Deliveries awaiting assignment to delivery personnel or awaiting pickup from the warehouse/branch.
• 5.11.3 In Transit: Active deliveries currently in progress with real-time GPS location updates. Administrators and buyers can view live tracking on Google Maps.
• 5.11.4 Delivered: Successfully completed deliveries with proof of delivery photos, delivery timestamp, recipient confirmation, and customer rating.
• 5.11.5 Failed: Failed delivery attempts with failure reason, attempted delivery timestamp, and follow-up action required. Supports rescheduling or return to sender.
• 5.11.6 My Deliveries: Personal delivery queue for delivery personnel showing only their assigned deliveries with navigation links and status update controls.

Role Permissions

Role	View	Update Status	Assign Personnel	Proof of Delivery
Super Admin	All	All	✓	✓
Admin	All	All	✓	✓
Delivery Personnel	Assigned Only	Assigned Only	—	Own
Buyer	Own Order	—	—	—

Dashboard Sidebar Path: Delivery Management → All Deliveries / Pending / In Transit / Delivered / Failed / My Deliveries

---

5.12 Selling Manager Module

Module Overview

The Selling Manager Module enables the dual-selling model that distinguishes Selfimart from conventional ecommerce platforms. Sellers can upload and sell their own products while receiving commission after platform fees are deducted. Resellers can generate unique referral codes for existing products and earn commissions on sales made through their codes.

Module Business Purpose

This module creates multiple earning opportunities within the platform ecosystem. It enables traditional product selling with configurable commission splits, reselling through unique referral codes with price-setting flexibility, and combined operations for store agents. The module drives platform growth through network effects where resellers actively promote products across their social networks, expanding market reach without additional marketing spend.

Sub-Modules

• 5.12.1 Reselling: Enables resellers to browse available products, generate unique reseller codes, set their selling price within the admin-defined range, and track code performance including views, clicks, and conversions.
• 5.12.2 Selling: Handles seller product management including product listing, pricing, inventory, and commission configuration. Sellers can view their product performance and sales analytics.
• 5.12.3 Browse Products: Product catalog view for resellers to discover and select products available for reselling. Shows product details, current pricing, allowed price range, and commission rate.

Role Permissions

Role	View Products	Generate Code	Set Price	View Earnings
Super Admin	All	—	Set Range	All
Admin	All	—	Set Range	All
Reseller	Available	✓	Within Range	Own
Seller	Own + Available	✓	Own Products	Own
Store Agent	Available	✓	Within Range	Own

Dashboard Sidebar Path: Selling Manager → Reselling / Browse Products / My Products

---

5.13 Commission Module

Module Overview

The Commission Module manages commission calculations, policy definitions, and payout processing for all platform stakeholders. It tracks earnings for sellers, resellers, delivery personnel, and the platform itself, with comprehensive policy management and full financial accounting through payables and receivables tracking.

Module Business Purpose

This module provides transparent and accurate commission tracking for all parties involved in a transaction. It supports flexible commission policies that can be configured per product category, seller, or reseller. The module handles the complete financial accounting cycle — from commission calculation at order completion through payout processing — and generates comprehensive financial reports for tax and audit purposes.

Sub-Modules

• 5.13.1 Commission History: Complete chronological record of all commission transactions including the triggering order, commission type (seller, reseller, delivery, platform), amount, calculation basis, and current status (pending, approved, paid).
• 5.13.2 Commission Policies: Defines the rules and rate structures for commission calculation. Policies specify commission percentages for different stakeholder types, applicable product categories, and calculation methods (percentage of profit vs. percentage of sale price).
• 5.13.3 Commission Structures: Hierarchical commission breakdown configurations showing how revenue from a single sale is distributed among the platform, seller, reseller, and delivery personnel. Structures can be assigned to specific products or categories.
• 5.13.4 Payables: Tracks amounts the platform owes to stakeholders (sellers, resellers, delivery personnel) that have been earned but not yet paid out. Supports batch payout processing with payment confirmation.
• 5.13.5 Receivables: Tracks amounts owed to the platform by stakeholders, such as platform fees deducted from seller earnings. Provides reconciliation tools for financial reporting.

Role Permissions

Role	View Own	View All	Manage Policies	Process Payouts
Super Admin	✓	All	✓	✓
Admin	✓	All	✓	✓
Seller	Own	—	—	—
Reseller	Own	—	—	—
Delivery Personnel	Own	—	—	—

Dashboard Sidebar Path: Commission → History / Policies / Structures / Payables / Receivables

---

5.14 Shipping Management Module

Module Overview

The Shipping Management Module handles all shipping-related configurations including customer shipping addresses, pickup point locations, and shipping fee structures. This module supports both doorstep delivery and pickup point collection options, giving customers flexibility in how they receive their orders.

Module Business Purpose

The module provides flexible shipping options for customers while enabling administrators to configure shipping costs based on delivery zone, order weight, or order value. It supports multiple delivery methods and integrates directly with the checkout process to display accurate shipping costs before order confirmation. Picking point management enables cost-effective collection options for customers in areas with reliable pickup infrastructure.

Sub-Modules

• 5.14.1 Shipping Addresses: Customer delivery address management with support for multiple saved addresses per account, default address selection, and address validation. Addresses include recipient name, phone, street address, city, county, and postal code.
• 5.14.2 Picking Points: Pickup location management with name, address, GPS coordinates, operating hours, contact phone, and capacity limits. Picking points are displayed on a map during checkout for easy selection.
• 5.14.3 Shipping Fees: Fee configuration based on delivery zones, weight brackets, or order value thresholds. Supports flat-rate, weight-based, and free shipping above a minimum order value. Urgent delivery surcharges can be configured separately.

Role Permissions

Role	View	Create	Edit	Delete
Super Admin	All	✓	All	✓
Admin	All	✓	All	—
Buyer	Own Addresses	Own	Own	Own

Dashboard Sidebar Path: Shipping Management → Shipping Addresses / Picking Points / Shipping Fees

---

5.15 Self-Checkout Module

Module Overview

The Self-Checkout Module implements the innovative "Scan & Go" feature that bridges physical retail with the ecommerce platform. Customers in physical stores can scan QR codes placed on products using their mobile devices, add items to a virtual cart through a Progressive Web App (PWA) interface, and complete payment directly from their phones — eliminating traditional checkout queues entirely.

Module Business Purpose

This module creates a seamless, modern in-store shopping experience that reduces checkout wait times and operational costs. It integrates physical retail inventory with the online platform, enabling real-time stock deduction upon successful payment and unified reporting across all sales channels. The PWA operates without requiring account registration, making it accessible to all customers regardless of whether they have a Selfimart account.

Sub-Modules

• 5.15.1 Sessions: Self-checkout session management and monitoring. Each session is created when a customer scans their first product and expires after a configurable timeout. Administrators can view active sessions, session history, and session details including items scanned and payment status.
• 5.15.2 Transactions: Complete transaction records for all self-checkout payments including session ID, items purchased, total amount, payment method, payment gateway reference, and transaction timestamp.
• 5.15.3 Reports: Analytics and reporting for self-checkout operations including daily/weekly/monthly transaction volumes, revenue, average basket size, most scanned products, and peak usage times.

Role Permissions

Role	View Sessions	View Transactions	View Reports	Manage QR Codes
Super Admin	All	All	All	✓
Admin	All	All	All	✓
Store Agent	Own Branch	Own Branch	Own Branch	Own Branch
Guest User	PWA Only	—	—	—

Dashboard Sidebar Path: Self-Checkout → Sessions / Transactions / Reports / QR Codes

---

5.16 Content Management Module

Module Overview

The Content Management Module handles all content-related operations including static page management, FAQ administration, product news articles, and promotional slider configuration. This module enables marketers and administrators to manage all informational content on the platform without requiring developer involvement.

Module Business Purpose

The module provides a user-friendly interface for content creators to manage website content independently. It supports SEO optimization through meta title and description management, content scheduling for timed publications, and dynamic content placement throughout the platform. Well-managed content improves search engine rankings, customer trust, and conversion rates.

Sub-Modules

• 5.16.1 Pages: Static page management with rich text editing via Quill editor. Pages include title, slug, meta description, content, category assignment, and publication status. Supports custom page categories for organized navigation.
• 5.16.2 FAQs: Question and answer management with category grouping for organized display. FAQs support rich text answers, ordering within categories, and active/inactive status for seasonal content.
• 5.16.3 Product News: Product announcement and news article management with title, featured image, content, publication date, and category. News articles appear in the dedicated news section of the public website.
• 5.16.4 Product Sliders: Homepage hero slider management with image upload, title, subtitle, call-to-action button text and link, display order, and active/inactive status. Multiple slides can be configured with automatic rotation.

Role Permissions

Role	View	Create	Edit	Delete
Super Admin	✓	✓	✓	✓
Admin	✓	✓	✓	✓
Marketer	✓	✓	✓	✓

Dashboard Sidebar Path: Content Management → Pages / FAQs / Product News / Product Sliders

---

5.17 Settings Module

Module Overview

The Settings Module provides centralized access to all system-wide configuration settings including site identity, contact information, operational parameters, and notification preferences. This module consolidates general platform settings in one location, reducing the need to search across multiple modules for configuration options.

Module Business Purpose

The module enables administrators to configure platform-wide settings that affect all users and operations. It provides a single location for system configuration, reducing the risk of inconsistent settings across modules and minimizing the need for code-level changes for routine configuration updates.

Features

• Site name, tagline, and meta description configuration
• Logo and favicon upload with automatic resizing
• Contact information management (phone, email, address, social media links)
• Operational settings including default commission rates and minimum order values
• Delivery fee defaults and free shipping threshold configuration
• Email notification preferences for order events
• Maintenance mode toggle with custom maintenance message
• Google Analytics and Facebook Pixel integration codes

Role Permissions

Role	View	Edit
Super Admin	✓	✓
Admin	✓	—

Dashboard Sidebar Path: Settings → System Settings

---

5.18 Audit Trail Module

Module Overview

The Audit Trail Module maintains comprehensive, tamper-evident logs of all user activities within the platform. This module provides accountability, security monitoring, and compliance support through detailed activity tracking powered by Spatie Laravel-Activitylog.

Module Business Purpose

The module ensures accountability by automatically recording all user actions with precise timestamps, IP addresses, user agent information, and detailed before/after change values for model modifications. It supports security investigations by providing a complete activity timeline for any user or resource, compliance audits by maintaining immutable records of all data changes, and operational troubleshooting by enabling administrators to trace the exact sequence of events leading to any system state.

Features

• Automatic logging of all model create, update, and delete operations
• User action tracking with complete before and after field values
• IP address and browser user agent logging for security analysis
• Searchable and filterable log interface with date range, user, and action type filters
• CSV/Excel export capabilities for compliance reporting and external audits
• Log retention policy configuration to manage storage usage

Role Permissions

Role	View Own	View All	Export
Super Admin	✓	All	✓
Admin	✓	All	✓
Developer	—	All	✓

Dashboard Sidebar Path: Audit Trail (Direct Link)

---

5.19 External Integration Module

Module Overview

The External Integration Module serves as the bridge between the Selfimart platform and external systems. This module enables third-party ERP systems, mobile applications, and external developers to interact with the platform through secure, well-documented RESTful APIs with comprehensive authentication and rate limiting.

Module Business Purpose

The module enables third-party supermarkets and retailers to connect their existing ERP or POS systems to the Selfimart platform without modifying their current infrastructure. It provides mobile application support through secure token-based API authentication and offers comprehensive interactive documentation for third-party development. The desktop agent download enables ERP systems without native API support to sync inventory and orders through a lightweight middleware application.

Sub-Modules

• 5.19.1 Mobile Apps: API endpoint management for mobile applications with token-based authentication via Laravel Sanctum. Includes mobile app credential management, token issuance, and API usage analytics.
• 5.19.2 ERP Requests: Third-party ERP integration management via webhooks or the downloadable desktop agent. Supports product catalog sync, inventory level updates, and order status synchronization between Selfimart and external ERP systems.
• 5.19.3 API Documentation: Interactive OpenAPI/Swagger documentation for all available API endpoints. Includes request/response examples, authentication instructions, and a live API testing interface.
• 5.19.4 SDK Generator: Automated SDK generation tools for multiple programming languages including PHP, JavaScript, Python, and Java. Generated SDKs include authentication helpers, typed request/response models, and usage examples.

Role Permissions

Role	Create Integration	Manage API Keys	View Documentation	Download Agent
Super Admin	✓	All	✓	✓
Admin	✓	All	✓	✓
Developer	✓	Own	✓	✓

Dashboard Sidebar Path: External Integration → Mobile Apps / ERP Requests / API Documentation / SDK Generator

---

6. Shopping Experience

6.1 Overview

The shopping experience in Selfimart encompasses the complete customer journey from initial product discovery through purchase completion and delivery tracking. The platform provides a seamless, intuitive shopping flow designed for maximum conversion and customer satisfaction. Every touchpoint — from the homepage hero slider to the post-delivery review prompt — is designed to guide customers naturally through the purchase funnel.

6.2 Product Discovery

Homepage Browsing Customers land on the homepage featuring a dynamic hero slider showcasing promotional content, featured categories with product previews, a new arrivals section, best sellers display, products on offer, and a newsletter subscription form. The homepage integrates with the Product Slider and Product Highlight modules to display fully dynamic, administrator-managed content.

Category Navigation The mega menu provides hierarchical category navigation with featured products displayed in dropdown panels. Customers can browse by top-level category, drill into subcategories, or navigate directly to brand pages using the navigation system. The mega menu is dynamically generated from the active category and brand database.

Search Functionality The search bar provides instant results with autocomplete suggestions as the customer types. Customers can search by product name, SKU, or description keywords. Advanced filtering allows narrowing results by price range, category, brand, availability status, and product highlights. Search results are ranked by relevance with sponsored products appearing at the top.

Product Highlights Products are tagged with highlight labels — New Arrival, Featured, On Offer, and Best Seller — for easy discovery. Dedicated highlight sections on the homepage and a highlight filter in the product catalog allow customers to browse specific highlight categories. Highlight assignments are managed through the Product Management module.

6.3 Product Viewing

Product Detail Page Each product displays comprehensive information including a full image gallery, detailed description, technical specifications, customer reviews with ratings, and a related products section. The page prominently shows the current price, offer price with savings percentage (if applicable), real-time stock status, and available delivery options with estimated delivery dates.

Image Gallery Multiple product images are displayed in an interactive gallery with zoom functionality. Customers can view all product angles and detail shots before making purchase decisions. The gallery supports swipe gestures on mobile devices for a native app-like experience.

Product Reviews Verified purchase reviews are displayed with star ratings, written comments, and reviewer names. Customers can filter reviews by star rating to read specific feedback. The overall rating is displayed prominently with a rating distribution chart. Sellers can respond to reviews through their dashboard.

Availability Check Real-time stock status is displayed on the product page, showing whether the product is in stock (with quantity if low), low stock (with urgency messaging), or out of stock. The system checks inventory across all branches and displays the most accurate availability information.

6.4 Cart Management

Adding to Cart Customers can add products to their cart from the product listing page (via quick-add button) or the product detail page (with quantity selection). The cart icon in the navigation updates in real time with the current item count and total value.

Cart Operations The cart page allows quantity adjustment with immediate price recalculation, individual item removal, and promotional code application with instant discount display. The real-time cart total calculation includes itemized subtotal, applied discounts, estimated shipping cost, and applicable taxes.

Cart Persistence Carts are automatically saved for logged-in users and persist across sessions and devices. Session-based carts for guest users are automatically merged with their account cart upon login, ensuring no items are lost during the authentication flow.

Wishlist Integration Items can be moved between the cart and wishlist with a single click. Wishlisted items display price change notifications when their prices are updated, encouraging customers to return and complete their purchase.

6.5 Checkout Process

The checkout process is divided into clear, sequential steps to minimize friction and maximize completion rates:

Step 1 — Delivery Type Selection The customer chooses between doorstep delivery or pickup point collection. Available options are displayed based on the products in the cart and the customer's location. Some products may require specific delivery methods.

Step 2 — Address or Pickup Selection For doorstep delivery, the customer selects from their saved shipping addresses or adds a new one. For pickup collection, the customer selects from available pickup points displayed on a map with distance, operating hours, and contact information.

Step 3 — Shipping Options Available shipping methods are displayed with their costs and estimated delivery timeframes. Urgent delivery options are available for an additional fee when configured. The customer selects their preferred shipping method before proceeding.

Step 4 — Payment Selection The customer selects their payment method from all configured and active gateways: Stripe (card), Paystack (card and mobile money), MTN MoMo (mobile money), or Pesapal (M-Pesa, card, bank transfer). The payment gateway integration handles all secure payment processing with PCI-compliant tokenization.

Step 5 — Order Review A final order summary displays all items with quantities and prices, applied discounts, delivery details, selected payment method, and the total amount to be charged. The customer can add special delivery instructions before confirming the order.

Step 6 — Confirmation Upon successful payment, an order confirmation page displays the order number, estimated delivery date, and tracking information. A confirmation email and SMS are automatically sent to the customer with order details and a tracking link.

6.6 Order Tracking

Order Status Updates Customers receive automatic notifications at each stage of the order lifecycle: Order Confirmed, Processing, Packed, Shipped, Out for Delivery, and Delivered. Status updates are pushed via email, SMS, and in-app notifications simultaneously.

Live Delivery Tracking For active deliveries, customers can view the delivery personnel's real-time location on an embedded Google Maps view. Integration with WhatsApp Business API enables the system to send live tracking links directly to the customer's WhatsApp, allowing tracking without opening the app.

Delivery Confirmation Customers confirm receipt of their delivery through the platform, which triggers the commission calculation process for all stakeholders involved in the order. A feedback and rating prompt is displayed immediately after confirmation.

6.7 Post-Purchase

Reviews and Ratings Customers can submit product reviews with a star rating (1–5), written comments, and optional photos. Reviews are submitted to a moderation queue and published after administrator approval. Only verified purchasers can submit reviews for a product.

Reorder Functionality Previous orders can be reordered with a single click from the purchase history. The system checks current product availability and pricing before adding items to the cart, notifying the customer of any changes since the original order.

Order History A complete purchase history is available in the customer dashboard with filtering by date range and order status, and export options for personal record-keeping. Each order entry links to the full order detail page with invoice download capability.

---

7. Public Facing Ecommerce Website Pages

The Selfimart public website consists of multiple page types serving different customer needs. All pages are built with responsive design for optimal display on desktop, tablet, and mobile devices.

7.1 Homepage (site.home)

The homepage serves as the main entry point for the public-facing website. It features a hero slider showcasing promotional content managed through the Product Sliders module, featured categories with product previews, a new arrivals section, best sellers display, products on offer, and a newsletter subscription form. All dynamic content sections are powered by the Product Highlight and Content Management modules.

User Capabilities:

• Browse featured products and categories with visual cards
• View promotional sliders and banners with call-to-action links
• Subscribe to the newsletter with email address
• Quick-add products to cart directly from product cards
• Navigate to category, brand, and individual product pages

7.2 Product Catalog (site.products.catalog)

The product catalog displays all available active products with comprehensive filtering, sorting, and pagination. It supports category filtering, brand filtering, price range filtering, keyword search, availability filtering, and highlight-based filtering. The page uses server-side DataTables for efficient rendering of large product catalogs without performance degradation.

User Capabilities:

• Filter products by category, subcategory, brand, price range, and availability
• Sort by product name, price (low to high / high to low), newest first, and popularity
• Add products to cart or wishlist directly from the catalog
• Quick-view product details in a modal without leaving the catalog
• Compare up to four products side by side

7.3 Single Product Page (site.products.show)

The single product page displays comprehensive product information including a full image gallery with zoom, detailed description, technical specifications table, customer reviews with ratings, and a related products carousel. It supports offer pricing display with savings percentage, real-time stock status indicators, delivery estimation, and social sharing buttons.

User Capabilities:

• View all product images with zoom and gallery navigation
• Select quantity and add to cart with immediate feedback
• Add to wishlist with one click
• Write and read verified purchase reviews
• Share product on social media platforms
• Check delivery options, costs, and estimated delivery dates

7.4 Category Page (site.products.category)

The category page displays all products within a specific category with subcategory navigation sidebar. It shows the category name, description, and featured image at the top, followed by subcategory filter chips and the product grid. Products can be further filtered and sorted within the category context.

User Capabilities:

• Browse all products within the selected category
• Filter by subcategory using the sidebar navigation
• View category description and featured products
• Apply additional filters (price, brand, availability) within the category

7.5 Brand Page (site.products.brand)

The brand page displays all products from a specific brand with the brand logo, name, and description prominently featured. Products are displayed in a filterable grid with category filter options specific to the brand's product range.

User Capabilities:

• Browse all products from the selected brand
• View brand information, logo, and description
• Filter brand products by category
• Sort and filter products within the brand context

7.6 Cart Page (site.cart.index)

The cart page displays all items currently in the customer's cart with quantity adjustment controls, individual item removal, and real-time price calculations. It supports promotional code application with instant discount display, delivery type pre-selection, and shipping address management before proceeding to checkout.

User Capabilities:

• Adjust item quantities with immediate total recalculation
• Remove individual items from the cart
• Apply promotional codes and view applied discounts
• Select delivery type (doorstep or pickup) as a pre-checkout step
• Add or select a shipping address
• Proceed to the multi-step checkout flow

7.7 Wishlist Page (site.wishlist.index)

The wishlist page displays all products saved by the customer with current pricing, stock status, and price change indicators. It supports moving individual items or the entire wishlist to the cart, sharing the wishlist publicly via a unique link, and removing items.

User Capabilities:

• View all saved products with current prices and stock status
• Move individual items or all items to the cart
• Share the wishlist via a unique public link
• Remove items from the wishlist
• View price change notifications for items with updated prices

7.8 Checkout Pages (site.checkout.*)

The checkout flow consists of multiple sequential pages: delivery type selection, shipping address or pickup point selection, urgency/shipping option selection, order review, and payment processing. Each step validates the previous step's data before proceeding.

User Capabilities:

• Select delivery method (doorstep delivery or pickup point collection)
• Add new or select existing shipping addresses
• Choose from available pickup points on an interactive map
• Select shipping speed and urgency options
• Review the complete order summary before confirmation
• Complete payment through the selected gateway
• Receive order confirmation with tracking information

7.9 Static Pages (site.pages.show)

Static pages display content managed through the Content Management module. Standard pages include About Us, Contact Us, Privacy Policy, Terms of Service, Return Policy, Cookie Policy, and Shipping Policy. Additional custom pages can be created by administrators and marketers through the CMS.

User Capabilities:

• Read informational content about the platform and policies
• Contact support via the contact form on the Contact Us page
• View all legal policies and terms of service
• Navigate between related pages via the page category navigation

7.10 Developer Portal (developer.*)

The developer portal provides comprehensive API documentation, mobile application integration guides, ERP connection instructions, and SDK generation tools. It serves external developers, integration partners, and technical teams who need to connect their systems to the Selfimart platform.

User Capabilities:

• View interactive OpenAPI/Swagger API documentation with live testing
• Download auto-generated SDKs for PHP, JavaScript, Python, and Java
• Learn about ERP integration options and download the desktop agent
• Access mobile app integration guides and authentication instructions
• Generate and manage API keys (for authenticated Developer role users)

7.11 Self-Checkout PWA (self-checkout)

The self-checkout Progressive Web App enables in-store customers to scan product QR codes and complete purchases entirely from their mobile devices without traditional checkout queues. The PWA operates without requiring account registration, making it accessible to all customers. It can be installed on mobile devices for a native app-like experience.

User Capabilities:

• Scan product QR codes using the device camera
• Add scanned items to a virtual cart with quantity adjustment
• View a running total with itemized product list
• Complete payment through the configured payment gateway
• Receive a digital receipt via email or SMS
• View transaction history for the current session

---

8. Support and Contact Information

8.1 System Administration Best Practices

Regular Backups Configure automated backups using the Spatie Backup package included in the platform. Schedule daily database backups and weekly full-system backups. Store backup archives in multiple locations — local storage and at least one cloud storage provider (AWS S3 recommended) — for disaster recovery resilience. Test backup restoration procedures quarterly.

Permission Audits Conduct monthly reviews of user permissions and role assignments to ensure appropriate access levels are maintained. Remove or deactivate accounts for users who are no longer active. Revoke unnecessary permissions that were granted temporarily. Document all permission changes in the audit trail.

Security Updates Keep all Composer and npm dependencies updated to the latest stable versions. Subscribe to security advisories for Laravel, Spatie packages, and all other installed dependencies. Apply security patches within 48 hours of release for critical vulnerabilities. Run composer audit regularly to check for known vulnerabilities.

Performance Monitoring Monitor system performance using Laravel Telescope in development and a dedicated monitoring service (such as New Relic, Datadog, or Laravel Pulse) in production. Optimize slow database queries identified through query logging. Enable Redis caching for frequently accessed data such as product catalogs, exchange rates, and settings. Configure queue workers for background job processing.

Audit Trail Review Periodically review audit logs for suspicious activities such as unusual login patterns, bulk data exports, or unexpected permission changes. Investigate anomalies promptly and implement corrective actions. Configure automated alerts for high-risk actions such as Super Admin account modifications.

8.2 Operational Recommendations

Commission Configuration Carefully configure commission policies before going live to ensure fair and accurate distribution among all stakeholders. Test commission calculations with sample orders before processing real transactions. Review commission rates periodically and adjust based on market conditions and stakeholder feedback. Ensure all commission policies are clearly communicated to sellers and resellers.

Inventory Management Maintain accurate inventory levels by conducting regular physical stock counts and reconciling with system records. Configure low-stock alert thresholds appropriate to each product's sales velocity. Use the stock transfer workflow for all inter-branch movements to maintain accurate branch-level inventory records. Investigate and resolve inventory discrepancies promptly.

Customer Support Train all chat agents on common customer issues, escalation procedures, and platform policies before they begin handling live chats. Monitor average response times and customer satisfaction ratings weekly. Establish clear escalation paths from chat to tickets to management for complex issues. Review and update FAQ content regularly based on common support queries.

Content Updates Keep website content fresh with regular product news updates, promotional slider changes, and FAQ additions. Remove outdated promotional content promptly to avoid customer confusion. Schedule content updates in advance using the publication date feature in the CMS. Ensure all static pages (Privacy Policy, Terms of Service) are reviewed and updated whenever platform policies change.

8.3 Development and Customization Guidelines

Code Standards Follow Laravel and PHP coding standards for all customizations. Use Laravel Pint for automated code formatting consistency. Follow PSR-12 coding standards for PHP. Write meaningful commit messages and maintain a clean Git history. Document all custom code with PHPDoc comments.

Testing Write comprehensive feature and unit tests for all new functionality. Maintain a minimum test coverage of 80% for critical business logic including commission calculations, payment processing, and order management. Run the full test suite before deploying any changes to production. Use Laravel Dusk for browser-based end-to-end testing of critical user flows.

Documentation Document all customizations, integrations, and configuration changes. Maintain an up-to-date technical README for the development team. Update this manual when new features are added or existing functionality changes. Use inline code comments to explain complex business logic.

Version Control Use Git for all code changes with a branching strategy (GitFlow recommended). Require code review via pull requests before merging to the main branch. Tag all production releases with semantic versioning. Never commit sensitive credentials or environment-specific configuration to the repository.

Deployment Use a CI/CD pipeline for automated testing and deployment. Deploy to a staging environment first and verify all functionality before promoting to production. Run database migrations with php artisan migrate during deployment. Clear all caches after deployment with php artisan optimize:clear.

8.4 Contact Information

For further consultation, technical support, custom development requests, or licensing inquiries, please contact:

Field	Details
Company	Gosuccess Technologies
Phone	+254714190255
Email	jayieko250@gmail.com

8.5 Support Hours

Day	Hours (EAT — East Africa Time)
Monday – Friday	8:00 AM – 6:00 PM
Saturday	9:00 AM – 1:00 PM
Sunday	Closed

Emergency Support: Critical system issues are supported 24/7 via email. Include "URGENT" in the subject line for priority response.

---

Document Version: 1.0.0 | Last Updated: April 2026

Copyright © 2026 Gosuccess Technologies. All Rights Reserved. Unauthorized reproduction or distribution of this document is prohibited.