MiniMart POS: A Complete Point-of-Sale System Built for Kenyan Businesses

Introduction

MiniMart POS is a full-featured point-of-sale and retail management system designed for small to medium-sized retail operations. Built on Laravel 12, styled with Tailwind CSS and AdminLTE, and engineered for both local development and cPanel shared hosting, MiniMart POS covers everything from the checkout counter to back-office inventory, reporting, and compliance.

What MiniMart POS Does

MiniMart POS is built around one goal: make the day-to-day retail workflow fast, accurate, and manageable from a single dashboard. It serves two distinct interfaces:

• Cashier / POS Interface — the sales floor, where attendants process sales, handle returns, scan barcodes, and manage customer interactions.
• Admin Interface — the back office, where the owner manages products, users, suppliers, purchases, reports, and system settings.

Both interfaces share the same database and the same business logic.

System Architecture

Tech Stack

Deployment Model

• Local development runs on SQLite (database/database.sqlite), so there is no need to install MySQL locally.
• Production is a standard cPanel shared-hosted Laravel app. The repository includes:
• deploy-to-cpanel.ps1 — a PowerShell script that packages the project into a zip while excluding vendor, node_modules, .git, tests, and runtime directories.
• .htaccess.cpanel.example — rewrite rules for hosts where the document root cannot be pointed at public/.
• app/Console/Commands/ExportMysqlDump.php — an Artisan command that converts the local SQLite database into a MySQL-compatible SQL dump for easy cPanel import.

Key Features

1. Point of Sale (Cashier)

The POS is the system’s core. It is designed for speed and clarity during high-traffic checkout.

Cart and checkout:

• Add products by barcode scan, manual search, or category selection.
• Adjust quantities on the fly.
• Support for multiple units of measure (UOM): products can be sold as individual units or whole packages (e.g., a “package” of 30 tablets), with prices recalculated automatically.
• Real-time cart totals and tax-aware line items.

Payment methods:

• Cash payments with automatic change calculation.
• M-Pesa STK Push integration, where the customer approves the payment directly on their phone. The system captures the M-Pesa receipt number, phone number, and payment status.
• Payment allocation across multiple methods when necessary.

Receipts and barcodes:

• Receipts are generated as views and can be printed from the browser.
• Product barcodes are served through a dedicated route (/pos/barcode/{text}) using a PNG barcode generator, so labels and reprints are always crisp.

Returns and refunds:

• Refunds are tied back to original sales and sale items.
• Restocked items are tracked so inventory stays accurate.

Customer loyalty:

• The system records and accumulates loyalty points on sales.
• Points are persisted at the sale level, giving the shop a foundation for future promotions.

2. Product Management (Admin)

The admin product catalog is more than a simple list. It is built for real inventory control.

Bulk operations:

• A select-all checkbox and per-row checkboxes allow bulk delete and bulk deactivation.
• Delete Selected hard-deletes products and their images from storage.
• Deactivate Selected sets is_active = false instead of deleting, preserving history while hiding inactive items from active workflows.

Import and export:

• Products can be exported to PDF, Excel, and CSV for auditing or sharing.
• A dedicated import template (XLSX) guides staff through the exact columns expected by the system.
• Full XLSX/CSV/ODS import with validation, supporting bulk product onboarding.

Inventory intelligence:

• Expiry date tracking per product.
• Low stock alerts driven by a configurable threshold (low_stock_threshold, falling back to minimum_stock).
• Multi-UOM support: a product can sell by “unit” or by “package,” and stock is always tracked in base units.
• Optional eTIMS fields (etims_item_cls_cd, etims_tax_ty_cd) for tax compliance integration.

Visual management:

• Products display buying price, selling price, stock quantity, category, shop, and expiry date.
• Image uploads are handled during create and update, with old images cleaned up on replacement.

3. Categories and Shops

• Categories organize products for browsing and reporting. Each product belongs to one category.
• Shops support multi-shop operations. Products, sales, purchases, and stock counts can be scoped to a specific shop, and reports can be segmented accordingly.

4. Customers

• Customer records include name, email, phone, address, and loyalty points.
• The admin panel provides full CRUD plus export capabilities.
• Customer search is available both in the admin list and from the POS checkout.

5. Purchases and Suppliers

• Suppliers are tracked with contact details and an active/inactive status.
• Purchases log supplier shipments, with line items for each product, quantities, and unit prices.
• Purchase payments track how much has been paid against each purchase, with support for cash and other methods.

6. User Management and Roles

MiniMart POS uses a simple but effective role model:

• Admin — full access to the admin panel, user management, reports, and settings.
• Cashier — restricted to the POS interface, daily revenue, shift closes, and opening balances.

Policies guard every admin resource so role enforcement is centralized and consistent.

7. Dashboard and Reports (Admin)

The admin dashboard gives a snapshot of business health. Below that, dedicated report sections provide:

• Daily Sales Report — sales for a selected day.
• Monthly Sales Report — aggregated by month.
• Profit Report — revenue minus cost of goods.
• VAT Report — VAT-eligible sales and tax amounts.
• Accounting Export — a downloadable accounting-ready export.

9. Notifications and Alerts

The system generates automated alerts for:

• Low stock — when a product’s quantity falls to or below its threshold.
• Expiring products — when expiry dates fall within a configurable warning window.

Notifications are stored in the database and surfaced through the admin interface, giving staff time to reorder or discount items before they become losses.

• Stock counts let teams perform physical inventory counts, compare against system quantities, and capture variances.
• Opening balances allow daily reconciliation of cash at the start of a shift.

11. M-Pesa Integration

• The STK Push flow prompts the customer to approve a payment on their phone.
• The callback endpoint captures the result, updates the sale, and records the M-Pesa receipt for reconciliation.
• Failed or pending payments are tracked and can be retried through the admin panel.

How It Works: A Typical Day

1. Opening balance is recorded at the start of the shift.
2. The cashier logs into the POS and begins ringing up sales. Products are found by barcode scan, search, or category. The cart supports multiple UOMs and M-Pesa or cash payment.
3. If a customer returns an item, the refund flow creates a refund record, optionally restocks the item, and links back to the original sale.
4. At the end of the shift, the shift close captures the final state.
5. Meanwhile, the admin monitors the dashboard, handles new purchase orders from suppliers, updates prices, imports new product batches, and reviews low-stock and expiry alerts.
6. At any point, the admin can run reports for VAT, profit, or daily revenue, and export them for the accountant.

Data Model Highlights

The system is organized around a clean relational schema:

• users — staff accounts with role (admin or cashier).
• products — catalog with pricing, stock, UOM, shop, expiry, low-stock threshold, and active flag.
• categories — product taxonomy.
• shops — multi-shop support.
• customers — CRM basics plus loyalty points.
• suppliers — vendor records.
• purchases and purchase_items — inbound stock.
• sales, sale_items, and sale_payment_allocations — transactions and their payment splits.
• refunds and refund_items — reverse transactions.
• expenses and expense_categories — operational costs.
• stock_counts and stock_count_items — physical inventory sessions.
• notifications — low-stock and expiry alerts.
• settings — application-wide configuration (currency, expiry alert window, etc.).

Local Development vs Production

Local

• Uses SQLite. No database server required.
• Run migrations with php artisan migrate.
• Backups are SQLite file copies gzipped to storage/app/backups/.

Production (cPanel)

• Uses MySQL, created via cPanel’s MySQL Databases tool.
• Database content is migrated from the local SQLite dump using php artisan db:export-mysql, which produces a minimart-mysql.sql file ready for phpMyAdmin import.
• The deploy-to-cpanel.ps1 script packages the application into a zip suitable for cPanel File Manager, excluding vendor and runtime directories.
• After upload, the admin runs php artisan migrate --force and sets up a cron job for the Laravel scheduler.

Security and Permissions

• Admin routes are protected by an admin middleware that checks $user->role === 'admin'.
• Cashier routes are protected by a cashier middleware.
• Form requests include CSRF tokens.
• Deletion and updates are protected by confirmation dialogs in the UI.

Extensibility

MiniMart POS is structured so new features slot into existing patterns:

• New admin pages follow the AdminLTE layout and Tailwind utility classes already in use.
• New reports extend the existing report controller pattern.
• New integrations (e.g., additional payment providers or tax APIs) can be added as new controllers or middleware without restructuring the core.

Conclusion

MiniMart POS is more than a cash register. It is a complete retail operations platform covering checkout, inventory, purchasing, accounting, and compliance. By combining Laravel’s robustness with a practical cPanel deployment path, it is equally comfortable on a developer’s laptop and on a live shop server.