1. System Overview

The Multi-Branch POS System is a self-hosted, web-based Point of Sale and retail management platform built for businesses that operate one or more physical locations — including locations in different countries with different currencies, tax rules, and timezones.

It combines a fast, offline-friendly checkout (POS) interface with a full back-office suite covering inventory, purchasing, suppliers, customers, loyalty, promotions, expenses, multi-branch stock transfers, financial/operational reporting, and system administration — all in one application, with no third-party SaaS subscription required.

Because it's self-hosted (runs on standard PHP/MySQL hosting — including affordable shared/cPanel hosting), the business that buys it owns the software outright, controls its own data, and isn't locked into recurring per-terminal or per-branch SaaS fees charged by typical cloud POS providers.

2. Core Architecture

2.1 Technology Stack

2.4 Multi-Branch & Multi-Currency Design

This is the architectural centerpiece of the system:

• Branch isolation, single database: every transactional table (sales, branch_stock, purchases, branch_expenses, etc.) is keyed by branch_id. One installation can run an unlimited number of branches without duplicating the application.
• Per-branch configuration: each branch independently controls its currency (symbol or code, from a curated list of African and global currencies, or a custom one), tax rate & label, invoice number prefix, timezone, theme color, working hours, and receipt header/footer.
• Branch-scoped access: a user's access is governed by user-to-branch mapping, where each user can be linked to one or more branches, each with its own role (e.g. Cashier at Branch A, Branch Manager at Branch B), and one branch flagged as their primary.
• Active branch context: the header's branch switcher sets the "active branch" for the session, which scopes the Dashboard, POS, Sales History, Stock, and most Reports.
• Permanent invoice numbering: invoice numbers are generated from the branch's prefix at the moment of sale and never change retroactively — preserving accounting integrity even if a branch's settings are later updated.

2.5 Security & Auditing

• Role-Based Access Control (RBAC) combined with a granular permission system (module-level checkboxes per role).
• Activity Logs capture who did what, when, from which IP, and — for record updates — a field-level before/after diff.
• Session timeout with a pre-expiry warning, and secure "Remember Me" tokens (HttpOnly cookies).
• IP detection is proxy/CDN-aware (X-Forwarded-For, X-Real-IP, CF-Connecting-IP) so audit logs show real visitor IPs even behind a reverse proxy on shared hosting.
• CSRF protection on state-changing forms.

3. Key Features

4. Problems It Solves

5. User Roles & Access Control

Access control combines two layers: a role (baseline permission set + numeric level) and fine-grained permissions (per module, e.g. inventory.manage, reports.view, settings.manage), customizable per role from Roles → Permissions.

Additional custom roles (e.g. "Supervisor", "Inventory Clerk", "Accountant", "Auditor") can be created at any time, each with its own name, level, and fully customizable permission checklist.

5.2 How Branch Scoping Works

• A user can be assigned to multiple branches, with a different role at each branch (e.g. Cashier at Lagos, Branch Manager at Abuja).
• One branch is flagged as the user's primary branch — their default active branch at login.
• For Cashiers/Branch Managers, almost all data (sales, stock, reports) is automatically filtered to only their assigned branch(es).
• Super Administrators and Admins can view a specific branch or, where supported, all accessible branches in aggregate (e.g. in reports).

6. Module Descriptions

A detailed, page-by-page walkthrough of every module is provided in the companion User Guide shipped with the product.

7. Browser & Hosting Compatibility

Browser Support

Modern evergreen browsers: Google Chrome, Microsoft Edge, Mozilla Firefox, and Safari (latest two major versions). The interface is responsive and usable on tablets; for the POS screen, a desktop/laptop or tablet with a physical or USB/Bluetooth barcode scanner is recommended for best throughput. Super admins, admins, and managers can also log in from their phones to follow up on sales and daily operations when the system is hosted on a public web server.

Hosting Compatibility

8. Who Is It Designed For?

Built for small-to-mid-sized retail and service businesses that need professional POS capabilities without ongoing SaaS costs or expensive custom development, including:

• Multi-branch retail chains — supermarkets, pharmacies, electronics stores, fashion/apparel chains, hardware stores operating two or more outlets, possibly across cities or countries.
• Single-store retailers planning to expand — the multi-branch architecture scales from one location to many without switching platforms.
• Businesses operating internationally or regionally — e.g. branches in Nigeria, Ghana, and a diaspora/export branch priced in USD — thanks to per-branch currency and tax configuration.
• Wholesalers and distributors with supplier purchase orders, batch/expiry tracking, and inter-branch stock transfers.
• Businesses running customer loyalty/rewards programs as part of their retention strategy.
• Software resellers / IT consultancies deploying white-labeled POS solutions for clients — install, brand, and support on behalf of multiple end-customers.
• Educational and demo environments — clean module separation makes it a strong base for teaching retail systems concepts or further customization.

9. Business Benefits