# Software Requirements Specification (SRS)

## Multi-Branch POS & Inventory Management System

| Field | Value |
|--------|--------|
| **Document version** | 1.0 |
| **Last updated** | 2026-05-12 |
| **Target stack** | HTML5, CSS3, JavaScript, jQuery, Bootstrap 5, PHP (procedural), MySQL |
| **Deployment context** | XAMPP / LAMP, single-tenant per installation |

---

## 1. Introduction

### 1.1 Purpose

This document specifies functional and non-functional requirements for a **modern, multi-branch Point of Sale (POS)** and inventory system. It is written so you (or Cursor AI) can implement the product **module by module** with consistent security, UX, folder layout, and reporting behaviour.

### 1.2 Intended audience

- Product owner / business stakeholders  
- Developers (PHP + MySQL)  
- QA / acceptance testers  
- Cursor AI agents (use **Section 16** as the master implementation prompt)

### 1.3 Definitions

| Term | Meaning |
|------|--------|
| **Branch** | A physical store or warehouse unit; stock, sales, and users can be scoped to branches. |
| **System Admin** | Highest privilege; hidden from normal admin user lists; global settings, SMS, limits, branch CRUD, feature toggles. |
| **Admin** | Full operational control across all branches except System Admin–only screens. |
| **POS** | Fast checkout screen for walk-in sales, barcode scanning, multiple payments. |
| **Due** | Outstanding payable (supplier) or receivable (customer) after partial payments. |
| **Shop type / software type** | Business vertical (e.g. electronics, cosmetics, books, clothing) that **enables vertical-specific fields and workflows**. |

---

## 2. Product vision & goals

- **Hassle-free transactions**: minimal clicks for sale/purchase/return; strong defaults; keyboard-friendly POS.  
- **Branch-aware**: same SKU can exist per branch with correct stock; users see only allowed branches.  
- **Auditable**: who did what, when, on which branch; adjustments and transfers traceable.  
- **Scalable lists**: smooth behaviour with **very large datasets** (e.g. 100k+ rows) via server-side filtering, pagination, and sensible indexes.  
- **Modern 2026 UI**: responsive (mobile, tablet, laptop, desktop), clear hierarchy, icons, dark/light optional later; accessible contrast.  
- **Bangla / English**: entire UI copy switchable from Settings (multilingual system).

---

## 3. User roles & permissions

### 3.1 Role hierarchy (high → low)

1. **System Admin**  
2. **Admin**  
3. **Manager**  
4. **Cashier**  
5. **Salesman**  
6. *(Optional)* **Stock keeper**, **Accountant** — add if business needs clearer separation.

### 3.2 System Admin (exclusive capabilities)

- Create / edit / **delete branches** (others cannot add/delete branches).  
- System admin profile (name, login, recovery): **only System Admin** can view/edit.  
- **Membership (customer group)** module enable/disable and policy.  
- **Reward points** global enable/disable; earn rules (per amount or % of sale); redeem rules if applicable.  
- **SMS** module: enable/disable, API URL, API key, sender ID, message templates (e.g. sale thank-you, payment due).  
- **Copyright / footer** text on printed/PDF documents and login screen (if desired).  
- **Max product limit**: system-wide cap; block or warn when exceeded.  
- **Software / shop type** selection and **per-type feature flags** (which extra fields are mandatory).  
- Full access to **all branches** and all reports.  
- **Visibility rule**: System Admin **must not appear** in user lists visible to Admin or lower roles (and Admin cannot edit/delete System Admin).

### 3.3 Admin

- Everything except **System Admin–only** settings and controls.  
- All branches: view, edit, delete operations as per permission matrix (except branch add/delete if reserved for System Admin per your spec).  
- User management including roles **except** managing hidden System Admin accounts.

### 3.4 Manager / Cashier / Salesman

- **Branch-scoped** by assignment: a user may be linked to **one or more branches**; they must not see other branches’ data.  
- Permissions granular per module: e.g. Salesman may create quotation but not approve purchase; Cashier may run POS but not stock adjustment.  
- **Configurable matrix** (recommended): rows = roles, columns = modules/actions (view/add/edit/delete/export/print).

### 3.5 Branch-wise user assignment

- On **user create/edit**, multi-select **branches**.  
- All queries for transactional data **must filter** by `branch_id IN (user_allowed_branches)` unless role is Admin (all branches) or System Admin.  
- **Default branch** per user for POS landing and default filters.

---

## 4. Global UI / UX requirements

### 4.1 Design language (2026)

- Bootstrap 5 grid + utility classes; custom CSS tokens for **primary/secondary/surface/border/radius/shadow**.  
- Card-based dashboards, clear typography scale, generous spacing, consistent icon set (e.g. Bootstrap Icons or Font Awesome).  
- **Responsive**: collapsible sidebar on small screens; touch-friendly tap targets (min ~44px) on POS.  
- Loading states: skeletons or spinners on async tables.  
- Empty states with short guidance (“No sales for this filter — try All or widen dates”).

### 4.2 Feedback: SweetAlert2 + sound

- **SweetAlert2** for success, validation error, confirm delete, and destructive actions.  
- **Short UI sounds** (non-intrusive, user-controllable in Settings):  
  - Success (save, payment complete)  
  - Error / validation failure  
  - Optional: scan beep on POS barcode success  
- Settings: **master toggle** “UI sounds” + volume or mute.

### 4.3 Multilingual (Bangla / English)

- All user-visible strings via a **language dictionary** (e.g. PHP arrays `lang/en.php`, `lang/bn.php` or JSON).  
- Active language from **Settings** (stored in DB + session); optional per-user override later.  
- Dates/numbers: locale-aware formatting where possible.  
- **RTL not required** for v1.

### 4.4 Barcode quality

- Invoices and **product label stickers**: barcode (CODE128 or EAN-13 if GTIN available); adequate **quiet zone**, size, and DPI-friendly SVG/canvas rendering.  
- POS: support USB scanner (keyboard wedge) + optional camera module later.  
- Labels: configurable **label size presets** (thermal 58mm / 80mm, etc.).

---

## 5. Standard list pages (applies to every major table)

Each list screen **must** include:

| Control | Behaviour |
|--------|------------|
| **Date filter** | Today, Yesterday, This month, All, **Custom range** (from–to date pickers). |
| **Branch filter** | Single branch, **All** (within user’s allowed branches). |
| **User filter** | Created by / sold by / adjusted by — as relevant to module. |
| **Typing filter** | Contextual: e.g. users → name, phone; products → name, SKU, barcode; customers → name, phone. |
| **Page size** | 25, 50, 100, 200, 500, **1000**, **All** (use “All” with caution — only when dataset bounded or server-streamed; prefer cap with warning). |
| **Pagination** | Server-side `LIMIT/OFFSET` or cursor-based; **indexed** columns for filter/sort. |
| **Footer text** | e.g. “Showing 1–15 of 200” (Bangla copy in BN locale). |
| **Export** | **Excel (CSV/XLSX)**, **PDF**, **Print** — **respect current filters** (export what you see). |
| **Print** | Print-friendly CSS (`@media print`), optional header/footer with business info. |

### 5.1 Performance (large data)

- Mandatory **indexes** on: `branch_id`, `created_at`, `invoice_no`, `customer_id`, `supplier_id`, `product_id`, `user_id`, barcode/SKU.  
- Avoid `SELECT *` in production queries; paginate **always** for HTML table view.  
- For exports of huge sets: **async job** + download link (optional phase 2) or streamed CSV.

---

## 6. Module-wise functional requirements

### 6.1 Authentication & session

- Secure login (password hashing **password_hash** PHP), lockout optional, session regeneration on login.  
- CSRF token on all state-changing forms and AJAX POSTs.  
- Idle timeout configurable.

### 6.2 Dashboard

- Widgets: **Total purchase**, **total sales**, **purchase due**, **sales due**, **purchase return**, **sales return**, **total expense** (all honour date + branch filters).  
- **Charts**: sales vs purchase, expense trend, top products (optional phase).  
- **Welcome text** (personalized: user name, branch).  
- Quick links: POS, Add sale, Add purchase (permission-based).

### 6.3 User management

- CRUD users; assign **role** and **branches**; optional employee code.  
- Password reset by Admin / System Admin only (policy configurable).  
- **Audit**: last login, IP (optional).

### 6.4 Supplier

- Supplier CRUD; ledger-style **purchase due** summary; **purchase return due** if applicable.  
- Supplier statement report (transactions + running balance).

### 6.5 Customer

- Customer CRUD; **sales due** balance; statement.  
- **Customer group / membership**: per-customer **flat or percentage discount** auto-applied on **invoice** and **POS sale** (subtract from line total or subtotal per your rule — document clearly: *recommended: apply % on subtotal before tax or after discount policy in settings*).  
- **Reward points** (if enabled): earn by spend; rules from Settings (e.g. X points per ৳100 or % of sale); display balance in customer search panel; redeem workflow optional in v1 or phase 2.  
- Customer search in POS/sales shows: **due**, **group/membership**, **points** (if on).

### 6.6 Products

- Product list, add/edit, categories, brands, **units** (kg, pcs, etc.).  
- **Multi-branch assignment** on product: which branches stock this SKU (or per-branch price/stock — see data model).  
- **Variations** (size, colour): parent product + variation attributes; separate SKU/stock per variation if needed.  
- **Label print** with barcode; bulk print from list filter.

### 6.7 Purchase

- Purchase list/add; **multi-payment** on purchase; affects stock **in** and supplier due.  
- **Purchase return**: stock **out**, financial credit, due adjustment.  
- **Electronics shop type**: **IMEI / serial capture per unit line** on purchase; sell by specific IMEI (see §7).

### 6.8 Sales

- Sales list/add; **POS screen** (fast search, barcode, cart, hold bill, discount, tax, multi-pay).  
- **Sales return** with stock and payment reversal.  
- **Quotation** list/add; convert quotation → sale (permission-based).

### 6.9 Stock transfer

- Transfer between branches: **out** from source, **in** to destination; statuses: Draft / In transit / Completed / Cancelled; approval optional.

### 6.10 Stock adjustment

- Reasons (damage, loss, found, recount); approval optional; never silent — always user + timestamp + branch.

### 6.11 Expense

- Expense categories; list/add; branch and user on record; attachments optional (phase 2).

### 6.12 Reports

- Profit & loss (revenue, COGS, expenses, gross/net profit — definitions in settings: valuation method FIFO suggestion).  
- Product purchase / sales reports.  
- Purchase payment / sales payment reports.  
- Expense report.  
- Stock adjustment report.  
- Combined purchase & sales.  
- **Product stock** by branch; low stock alert (optional).  
- All reports: standard filters + export.

### 6.13 Settings

- **Business information**: name, logo, address, VAT/TIN, phone, email.  
- **Invoice settings**: template for **A4** vs **POS/thermal**; paper size; footer note; barcode on invoice.  
- **System admin information** (System Admin only).  
- **Software type** (shop type) — drives §7.  
- **Language** default.  
- **Payment methods** master list (Cash, Card, bKash, Nagad, Bank, etc.) — used in purchase/sale/POS; **cashbook-style** report: filter by method and see amounts per account/method (define “account” as optional ledger dimension).

### 6.14 Payment methods & “money in account”

- CRUD payment methods (name, type: cash/bank/mobile/bard, active flag).  
- Optional **linked ledger account** per method for accounting-oriented export.  
- On sale/purchase: **split payments** across methods; stored per invoice.  
- Reports: filter by date, branch, user, **payment method**; totals per method.

---

## 7. Shop-type vertical profiles (System Admin controlled)

When a type is selected, **activate module flags** and **required fields**. Examples:

| Shop type | Extra fields / behaviour |
|-----------|---------------------------|
| **Electronics** | Product: warranty period; **IMEI/serial mandatory** on applicable items. Purchase: **one row per IMEI** entry or quantity expansion into serial list. Sale/POS: pick IMEI from available pool; block duplicate sale of same IMEI; IMEI search in warranty lookup. |
| **Books** | Author, publisher, ISBN; optional edition/year; search by ISBN. |
| **Cosmetics** | Batch/lot, **expiry date** (optional mandatory), manufacturing date; expiry warning report. |
| **Clothing** | Strong use of **variations** (size/colour), SKU per variant; optional season/collection. |
| **Generic retail** | Minimal extra fields; variations optional. |

System Admin can **override** which sub-features are mandatory per installation.

---

## 8. Additional features (recommended beyond your list)

- **Backup / restore** helper for MySQL (Admin/System Admin only).  
- **Activity log** (audit trail) for CRUD on masters and all financial docs.  
- **Tax/VAT** configuration per branch or global.  
- **Price tiers**: retail / wholesale (optional).  
- **Opening stock** wizard for new branch.  
- **Reorder level** alerts per product per branch.  
- **Cash register session** (open/close shift) for Cashier — optional but valuable.  
- **Duplicate invoice prevention** (idempotency key or short-term lock).  
- **Offline-first POS** — out of scope for v1 unless explicitly requested.  
- **Role-based dashboard widgets** (Cashier sees POS-focused shortcuts only).

---

## 9. Data model (high level)

**Core entities** (each major entity: `id`, `branch_id` where applicable, `created_at`, `created_by`, `updated_at`, `updated_by`, `is_deleted` soft delete optional):

- `branches`, `users`, `roles`, `permissions`, `role_permissions`, `user_branches`  
- `suppliers`, `customers`, `customer_groups`, `customer_group_discounts`, `customer_reward_balances`, `reward_transactions`  
- `categories`, `brands`, `units`, `products`, `product_branches`, `product_variations`  
- `imei_serials` (item-level: status in_stock/sold/returned, refs to purchase/sale lines)  
- `purchases`, `purchase_items`, `purchase_payments`, `purchase_returns`, …  
- `sales`, `sale_items`, `sale_payments`, `sale_returns`, …  
- `quotations`, `quotation_items`  
- `stock_transfers`, `stock_transfer_items`  
- `stock_adjustments`, `stock_adjustment_items`  
- `expenses`, `expense_categories`  
- `payment_methods`, `settings`, `shop_type_settings`, `languages`, `audit_logs`

**Referential integrity**: InnoDB, foreign keys where practical; cascade rules explicit (prefer restrict on financial tables).

---

## 10. Security requirements

### 10.1 Server-side

- **Prepared statements** (mysqli or PDO) for **all** DB access — no string-concatenated SQL with user input.  
- **Password_hash** / **password_verify**; minimum password policy in settings.  
- **CSRF** tokens on forms and AJAX.  
- **Output escaping** (`htmlspecialchars`) for all dynamic HTML.  
- **Authorization check** on every PHP page and API script: central `require_login.php` + `require_permission('sales','view')`.  
- **File uploads** (if added): whitelist MIME, store outside web root or non-executable, random filenames.  
- **HTTP headers**: `Content-Security-Policy` baseline, `X-Frame-Options`, secure cookie flags on HTTPS.  
- **Rate limit** login attempts (optional).  
- **Least privilege** DB user for application (not root).

### 10.2 Client-side

- No secrets in JS; barcode and sounds are public assets only.  
- Validate for UX; **never trust** client validation alone.

---

## 11. Folder & file structure (recommended)

Procedural PHP with clear separation — **not** full MVC required, but **disciplined includes**:

```
/public
  /index.php                 (router or front controller — optional)
  /login.php
  /logout.php
  /dashboard.php
  /pos.php
  /assets
    /css
    /js
    /img
    /sounds
  /.htaccess                 (deny PHP in uploads if uploads under public — better: store uploads outside)

/application
  /config
    database.php
    app.php
  /includes
    init.php                   (session, autoload paths, timezone)
    auth.php
    permissions.php
    csrf.php
    db.php
    functions.php
    lang.php
  /modules
    /dashboard
    /users
    /suppliers
    /customers
    /products
    /purchases
    /sales
    /pos
    /quotations
    /transfers
    /adjustments
    /expenses
    /reports
    /settings
  /partials
    header.php
    sidebar.php
    footer.php
    table_filters.php
    pagination.php

/storage
  /logs
  /backups
  /uploads                   (outside public if possible)

/lang
  en.php
  bn.php

/install                     (optional one-time installer; delete after use)
/sql
  schema.sql
  migrations/
```

**Per module pattern** (example `products`):

- `application/modules/products/list.php` — HTML table + filters  
- `application/modules/products/save.php` — POST handler (redirect)  
- `application/modules/products/delete.php`  
- `application/modules/products/ajax_search.php` — JSON for selects  
- `application/api/` optional thin JSON endpoints if separating AJAX

---

## 12. Coding & naming conventions

- **UTF-8** everywhere (`mb_*` where needed); DB `utf8mb4_unicode_ci`.  
- One responsibility per script where possible; shared logic in `functions.php` or small include files.  
- Consistent naming: `snake_case` in DB, `camelCase` in JS, PHP variables `$row_count` style.  
- Central constants for statuses (`SALE_STATUS_COMPLETED = 2`).  
- **Money**: store as **integer minor units** (e.g. poisha) or DECIMAL(19,4) — pick one and stick to it; never float.

---

## 13. Invoice & printing

- **A4** HTML template + print CSS.  
- **Thermal**: narrow template, logo optional, barcode, QR for invoice URL optional.  
- Invoice number format configurable (`INV-{BRANCH}-{YYYY}-{SEQ}`).  
- Duplicate print count in audit (optional).

---

## 14. Acceptance criteria snapshots

- Branch-restricted user never receives rows from forbidden `branch_id` (verify by SQL log / tests).  
- System Admin never listed for Admin in `users` module.  
- Every destructive action shows SweetAlert confirm + sound on result.  
- Switching language in Settings reloads UI strings without broken encoding.  
- Electronics mode: cannot complete purchase/sale of tracked item without valid IMEI state transitions.  
- List page with 100k sales: first page loads under agreed threshold (e.g. < 2s on reference hardware) with proper indexes.

---

## 15. Non-functional requirements

- **Availability**: single-store deployment; nightly backup recommended.  
- **Maintainability**: schema in versioned SQL files; comments on complex queries.  
- **Accessibility**: form labels, focus states, readable errors.  
- **Browser support**: latest Chrome/Edge/Firefox; ES5-friendly JS if needed for older browsers.

---

## 16. Cursor AI — master implementation prompt (copy-paste)

Use the following as a **high-priority system prompt** when building this project in Cursor:

> You are implementing a **multi-branch POS** in **HTML, CSS, JS, jQuery, Bootstrap 5, procedural PHP, MySQL** per `docs/SRS_POS_Software.md`.  
> **Security**: prepared statements everywhere; CSRF on all mutations; htmlspecialchars on output; password_hash for passwords; permission checks on every page.  
> **Data rules**: branch-scoped queries for all non–System Admin users; System Admin hidden from other admins’ user lists; branch and product multi-assignment as specified.  
> **UI standards**: every list page implements date, branch, user, contextual search, pagination sizes (25–1000, All with safeguards), “Showing X–Y of Z”, export Excel/PDF/print respecting filters, SweetAlert2, optional UI sounds toggle.  
> **Features**: implement modules in order — auth → settings shell → branches → users/roles → masters (units, categories, brands, payment methods) → products (+ shop-type extras) → purchase/return → sales/POS/return → quotations → transfers → adjustments → expenses → reports → dashboard polish.  
> **i18n**: all strings from `lang/en.php` and `lang/bn.php`; language from DB settings.  
> **Shop types**: implement feature flags so electronics requires IMEI lifecycle; books author/publisher/ISBN; cosmetics batch/expiry; clothing variations.  
> **Design**: modern responsive 2026 UI, icons, card layout, mobile sidebar.  
> **Barcode**: high-quality rendering on invoices and labels.  
> Do not invent conflicting business rules — when ambiguous, add a **settings toggle** and document default.

---

## 17. Traceability matrix (sample)

| SRS § | Module | Priority |
|-------|--------|----------|
| 6.2 | Dashboard | P0 |
| 6.3 | Users & permissions | P0 |
| 6.6–6.8 | Products, Purchase, Sales, POS | P0 |
| 6.9–6.10 | Transfers, Adjustments | P1 |
| 6.12 | Reports | P1 |
| 6.13–6.14 | Settings, payments | P0 |
| 7 | Shop types | P1 (flags P0) |
| 4.3 | Multilingual | P1 |
| 5 | Standard tables | P0 |

---

## 18. Glossary (Bangla ↔ English hints for UI)

| English key | বাংলা (example UI) |
|-------------|-------------------|
| Total sales | মোট বিক্রয় |
| Sales due | বিক্রয় বাকি |
| Purchase due | ক্রয় বাকি |
| Reward points | রিওয়ার্ড পয়েন্ট |
| Membership | মেম্বারশিপ / গ্রুপ |

*(Expand in `lang/bn.php` during implementation.)*

---

## 19. Document maintenance

- Update version table on each change.  
- Record **business rules** for discount/tax in appendix when finalized.  
- Keep **SQL migrations** aligned with SRS sections.

---

**End of SRS**