iquipe/quickretail repository overview

⁠QuickRetail Store Books

Featuring Double-Entry General Ledger, Role-Based Access Control (RBAC), Ghanaian Cedi (₵) native currency, Mailgun Daily Financial Email Digests, and Paystack Online Payments (Card & Mobile Money).

⁠Key Features

⁠1. QuickBooks-Style Accounting Engine

• Automated Double-Entry Ledger: Every sale, inventory purchase, operating expense, capital injection, and loan repayment creates balanced debit and credit entries (journal_entries).
• Standard Chart of Accounts: Pre-configured with Assets (1000s), Liabilities (2000s), Equity (3000s), Sales Income (4010), Cost of Goods Sold (5010), and Operating Expenses (6000s).
• Real-Time Financial Statements:
  • Profit & Loss (P&L): $$\text{Net Profit / Loss} = \text{Sales Revenue} - (\text{Cost of Goods Sold} + \text{Operating Expenses})$$
  • Balance Sheet: Balanced view of $\text{Assets} = \text{Liabilities} + \text{Owner's Equity}$.
  • General Ledger Audit Trail: Chronological journal with reference links and debit/credit verification.

⁠2. Ergonomic Point of Sale (POS) Cashier Cockpit

• Zero-Scroll Fixed Workstation (100vh): Eliminates outer browser scrolling and pinned checkout area to ensure fast retail throughput.
• Instant Product Search: Live SKU, Barcode, and Name search with category pills filter.
• Cart & Tender Controls: Quantity steppers, discount calculator, tender presets (Exact, ₵20, ₵50, ₵100), and automatic change calculation.
• Multiple Payment Methods: Cash, Bank Card / Transfer, Store Credit (Debtors), and Paystack Online (Mobile Money / Cards).
• 80mm Thermal Receipt Modal: Formatted for standard POS thermal receipt printers with one-click printing (window.print()).

⁠3. Price List & Inventory Management

• Merchandise Catalog: SKU, Barcode, Name, Category, Wholesale Cost Price, Retail Selling Price, Stock on Hand, and Alert Levels.
• Automated Stock Deductions & Replenishments: POS sales automatically deduct inventory; supplier purchase bills increase stock units.
• Valuation Analytics: Total units on hand, wholesale inventory valuation, retail value, and projected gross profit margin.

⁠4. Role-Based Access Control (RBAC)

• Store Owner (owner): Unrestricted master access to all retail modules, capital injections, business loans, bank accounts, complete P&L statements, Mailgun/Paystack API settings, and Factory Reset.
• Store Manager (manager): Operational access limited to POS register, Stock-In purchases, sales records, bills/expenses, debtor accounts, and supplier creditors. Restricted from capital, loan books, P&L reports, and settings.

⁠5. Mailgun Automated Daily Financial Digest

• Nightly Financial Summary: Aggregates daily sales revenue, COGS, operating expenses, and net profit/loss into a branded HTML email.
• Tender & Product Breakdown: Detailed breakdown of Cash vs. Bank vs. Credit vs. Paystack sales and top-selling merchandise.
• Automated Cron Script: Built-in cron_daily_report.php⁠ ready for Windows Task Scheduler or Linux Cron.
• Owner Control: Ability to toggle Mailgun ON/OFF, test credentials, and trigger manual email dispatches in Settings.

⁠6. Paystack Online Payments (Card & Mobile Money)

• Native Ghanaian Cedi (GHS / ₵): Handles automated conversion between Cedis and subunits (pesewas).
• Official Inline JS SDK: Allows customers to pay with Visa/Mastercard debit cards or Mobile Money (MTN, Vodafone, AirtelTigo) directly at the POS register without redirecting away from the terminal.
• Server Verification: Verifies transaction status via Paystack's REST API before deducting inventory, logging revenue to the Bank ledger, and printing receipts.
• Owner Control: Ability to toggle Paystack ON/OFF and verify API keys in Settings.

⁠7. Factory Reset Engine

• Clean Empty Database (Production Ready): Wipes all sample dummy products, customers, and test sales for immediate real-world shop operations. Keeps standard Chart of Accounts and logins.
• Fresh Demo Store (Simulation Mode): Re-seeds sample apparel merchandise, demo customers, suppliers, and test transactions for evaluation.
• Safety Safeguard: Requires typing RESET to prevent accidental erasure.

⁠System Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                        QuickRetail Store Books                         │
└────────────────────────────────────────────────────────────────────────┘
          │                                            │
          ▼                                            ▼
┌───────────────────┐                         ┌──────────────────┐
│   POS Register    │ (Deducts Stock)         │ Purchases (Stock)│ (Adds Stock)
│  Fast Barcode/SKU │────────────────────────►│  Supplier Bills  │──────────────┐
│  Cash/Card/MoMo   │ (Records Sales & COGS)  │ Cash/Bank/Credit │              │
└───────────────────┘                         └──────────────────┘              │
          │                                            │                        │
          ▼                                            ▼                        ▼
┌────────────────────────────────────────────────────────────────────────┐      │
│                     Double-Entry Accounting Engine                     │◄─────┘
│                      (includes/Accounting.php)                         │
│  - Sales Revenue (4010)             - Cost of Goods Sold (5010)        │
│  - Inventory Asset (1040)           - Operating Expenses (6000s)       │
│  - Cash & Bank (1010/1020)          - Customer Debtors (1030)          │
│  - Supplier Creditors (2010)        - Loans & Capital (2020/3010)      │
└────────────────────────────────────────────────────────────────────────┘
          │                                            │
          ▼                                            ▼
┌──────────────────────────────────────┐   ┌─────────────────────────────┐
│       Financial Statements           │   │      Integrations Engine    │
│  1. Profit & Loss Statement (P&L)    │   │  - Mailgun Daily Digest     │
│  2. Balance Sheet (A = L + E)        │   │  - Paystack Card/MoMo POS   │
│  3. General Ledger Audit Trail       │   │  - Factory Reset Control    │
└──────────────────────────────────────┘   └─────────────────────────────┘

⁠Tech Stack & Requirements

• PHP: 8.0, 8.1, 8.2, or higher.
• Database: SQLite 3 (pdo_sqlite extension enabled). Zero-configuration, file-based database stored in data/bookkeeping.db.
• Frontend: Bootstrap 5.3, Bootstrap Icons 1.11, Chart.js 4.4, Paystack Inline JS.
• Network / APIs: PHP curl extension for Mailgun & Paystack REST APIs.
• Dependencies: Zero Composer dependencies — completely self-contained and portable!

⁠Setup & Installation

⁠Option A: Running with XAMPP (Recommended on Windows)

1. Place Project in XAMPP htdocs: Copy or clone the book folder into your XAMPP web root directory:

   C:\xampp\htdocs\book   (or E:\xampp\htdocs\book)
   

   Copy

2. Verify PHP Extensions in php.ini: Ensure the following extensions are enabled in your php.ini file (remove the leading ; if present):

   extension=pdo_sqlite
   extension=sqlite3
   extension=curl
   extension=mbstring
   

   Copy

3. Start Apache: Open XAMPP Control Panel and click Start on Apache.

4. Open in Browser: Navigate to:

   http://localhost/book/
   

   Copy

   The database and tables will automatically initialize on the very first run!

⁠Option B: Running with PHP Built-in Server (Development / Standalone)

1. Open your terminal (PowerShell, Command Prompt, or Bash) in the project directory:

   cd e:\xampp\htdocs\book
   

   Copy

2. Start the built-in development server:

   php -S 127.0.0.1:8000
   

   Copy

3. Open your browser and go to:

   http://127.0.0.1:8000/
   

   Copy

⁠Option C: Running with Docker & Docker Compose (Containerized)

1. Ensure Docker Desktop (or Docker Engine + Compose) is installed and running.

2. In the project root directory, build and launch the container in detached mode:

   docker compose up -d --build
   

   Copy

3. Open your browser and navigate to:

   http://localhost:8000/
   

   Copy

4. Persistent Data: The SQLite database (bookkeeping.db) and execution logs (cron.log) are mounted to ./data on your host machine, ensuring your financial records persist safely across container rebuilds.

5. To view container status and logs:

   docker compose ps
   docker compose logs -f
   

   Copy

6. To stop the container:

   docker compose down
   

   Copy

⁠Default Credentials & Roles

⁠Configuration Guide

⁠1. Mailgun Daily Financial Email Digest

1. Log in as Store Owner (owner / owner123).
2. Go to "Integrations & Settings" in the sidebar.
3. Toggle "Enable Mailgun Daily Reports" ON.
4. Enter your Mailgun configuration:
   • Mailgun Domain: e.g. mg.yourdomain.com or sandboxXXXXX.mailgun.org.
   • Mailgun API Key: e.g. key-xxxxxxxx or API sending key.
   • API Region: US (api.mailgun.net) or EU (api.eu.mailgun.net).
   • Recipient Email: Owner inbox where digests should be delivered.
5. Click "Save Mailgun Settings", then click "Send Test Email" to verify connection.
6. Click "Dispatch Today's Digest Now" to receive today's financial digest immediately.

⁠Automated Nightly Cron Job

To automatically dispatch the report every night at 9:00 PM (21:00):

• Linux / cPanel Cron:

  0 21 * * * /usr/bin/php /var/www/html/book/cron_daily_report.php >/dev/null 2>&1
  

  Copy
• Windows Task Scheduler:
  • Action: Start a program
  • Program: php.exe
  • Arguments: e:\xampp\htdocs\book\cron_daily_report.php
  • Trigger: Daily at 21:00.

Logs are recorded in data/cron.log⁠.

⁠2. Paystack Online Payments

1. In "Integrations & Settings", toggle "Enable Paystack Online Payment in POS" ON.
2. Enter your Paystack keys:
   • Public Key: pk_test_... or pk_live_...
   • Secret Key: sk_test_... or sk_live_...
   • Currency: Locked to GHS (Ghanaian Cedi).
3. Click "Save Paystack Settings" and "Verify Paystack Keys" to confirm API authentication.
4. In the POS Register, the cashier can now select the Paystack tender option to accept Card or Mobile Money payments.

⁠3. Factory Reset (Clean Database for Production)

1. Go to "Integrations & Settings" and scroll to "Danger Zone: Database Factory Reset".
2. Choose your mode:
   • Clean & Empty Database (Production Ready): Erases all sample products, demo sales, dummy customers, and transactions so you can start entering actual store data.
   • Fresh Demo Store (Simulation Mode): Re-seeds sample merchandise, dummy customers, and test sales.
3. Type RESET in the confirmation box and click "Reset Database".

⁠Directory Structure

book/
├── assets/
│   └── css/
│       └── style.css            # Custom styling & POS 100vh cockpit layout
├── config/
│   └── db.php                  # SQLite connection, auto-migrations & seeders
├── data/
│   ├── bookkeeping.db          # SQLite persistent database file
│   └── cron.log                # Nightly report dispatch execution logs
├── includes/
│   ├── Accounting.php          # Core double-entry ledger & COGS engine
│   ├── Auth.php                # Session authentication & RBAC guards
│   ├── footer.php              # Global footer & modal templates
│   ├── header.php              # Global navigation, badges & RBAC sidebar
│   ├── MailgunService.php      # Mailgun REST API & HTML digest builder
│   └── PaystackService.php     # Paystack REST API & verification
├── api.php                     # AJAX backend (checkout, search, payments)
├── capital_loans.php           # Owner capital, loans & repayment splitting
├── cron_daily_report.php       # CLI/Cron automated daily email dispatcher
├── customers.php               # Customer debtor accounts & payment receipts
├── expenses.php                # Operating expenses categorization & logs
├── index.php                   # Executive financial dashboard & KPI charts
├── login.php                   # Login page with 1-click demo buttons
├── logout.php                  # Session logout handler
├── pos.php                     # POS cashier workstation & thermal receipt
├── products.php                # Price list, wholesale cost & inventory
├── purchases.php               # Purchases & supplier stock-in bills
├── reports.php                 # P&L Statement, Balance Sheet & Ledger
├── sales.php                   # Sales invoice history & margin analytics
├── settings.php                # Owner Integrations (Mailgun, Paystack, Reset)
├── suppliers.php               # Supplier creditor accounts & vouchers
├── .dockerignore               # Files ignored by Docker build context
├── Dockerfile                  # Container definition (PHP 8.2 + Apache + SQLite)
├── docker-compose.yml          # Container orchestration & port/volume mappings
├── LICENSE                     # MIT License
└── README.md                   # Complete system documentation

⁠License

This software is released under the MIT License⁠. You are free to use, modify, distribute, and integrate it for personal or commercial projects.