# ERP User Guide

A complete guide to using the ERP system for daily operations.

---

## Table of Contents

1. [Getting Started](#1-getting-started)
2. [Dashboard](#2-dashboard)
3. [Sales & Billing](#3-sales--billing)
4. [POS (Point of Sale)](#4-pos-point-of-sale)
5. [Inventory Management](#5-inventory-management)
6. [Purchases](#6-purchases)
7. [Accounting](#7-accounting)
8. [Banking](#8-banking)
9. [Reports](#9-reports)
10. [Setup & Administration](#10-setup--administration)
11. [Backups & Google Drive Sync](#11-backups--google-drive-sync)
12. [Keyboard Shortcuts](#12-keyboard-shortcuts)
13. [Mobile Usage](#13-mobile-usage)
14. [FAQ](#14-faq)

---

## 1. Getting Started

### Logging In
1. Open the ERP URL in your browser (e.g., `http://127.0.0.1:8123`)
2. Enter your email and password
3. Click **Sign In**

### Navigation
- **Sidebar** (left): All modules are organized into collapsible groups — Sales, Inventory, Purchases, Accounting, Reports, Banking, Setup
- **Hamburger menu** (top-left, three dashes): Toggle the sidebar open/closed
- **Collapsible groups**: Click a group label (e.g., "Sales") to expand or collapse it
- **Top bar**: Shows the current page name, action buttons, company switcher (for admins), and sign out

### Company Switching (Platform Admin)
If you manage multiple companies, use the company dropdown in the top bar to switch between them. All data shown will be for the selected company.

---

## 2. Dashboard

The dashboard (`/dashboard`) gives you an overview of your business:

### Key Metrics (Top Cards)
- **Total Sales**: Sales amount for the current period
- **Collections**: Money received from customers
- **Purchases**: Total purchases for the period
- **Expenses**: Total expenses recorded
- **Cash & Bank Balance**: Total liquid funds
- **Receivables**: Outstanding amount from customers
- **Payables**: Outstanding amount to suppliers
- **Stock Value**: Current inventory valuation
- **Gross Profit**: Sales minus cost of goods sold
- **Low Stock Items**: Products below reorder level
- **Pending Estimates**: Unconverted estimates
- **Overdue Invoices**: Invoices past their due date

### Setup Checklist
Shows initial setup tasks (Chart of Accounts, Products, etc.) with checkmarks when complete.

### Quick Access Cards
Shortcuts to frequently used pages like Sales Report, New Invoice, etc.

---

## 3. Sales & Billing

### 3.1 Estimates (Quotations)
**Path**: Sales > Estimates (`/estimates`)

- **Create Estimate**: Click "New Estimate" to create a quotation
- Add customer, line items, quantities, prices, and tax
- Estimates can be converted to invoices later
- **Print**: Click the print icon to generate an A4 printout

### 3.2 Invoices
**Path**: Sales > Invoices (`/invoices`)

- **Create Invoice**: Click "New Invoice"
- Select customer, add products, set quantities and prices
- The system auto-calculates subtotal, tax, and grand total
- **Post Invoice**: Click "Post" to finalize — this:
  - Generates a sequential invoice number
  - Posts to the general ledger (AR, Sales, Tax)
  - Updates stock (reduces inventory, calculates COGS)
- **Print**: Print A4 or 80mm (thermal printer) format
- **Cancel**: Cancel a posted invoice with a reason (creates a reversal entry)

### 3.3 Customers
**Path**: Sales > Customers (`/customers`)

- Add customers with name, address, phone, email, tax number
- View customer balance (receivables)
- Edit customer details anytime

### 3.4 Receipts (Customer Payments)
**Path**: Sales > Receipts (`/receipts`)

- Record payments received from customers
- Supports split payments (cash + bank + cheque + card + mobile)
- Allocate payments to specific invoices
- Supports TDS (tax withholding) lines

### 3.5 Sales Returns
**Path**: Sales > Sales Returns (`/sales-returns`)

- Process customer returns
- Creates stock receipt and GL reversal
- Links back to the original invoice

### 3.6 Price Lists
**Path**: Sales > Price Lists (`/price-lists`)

- Create price lists for different customer tiers
- Set quantity-based pricing breaks
- Assign price lists to customers

### 3.7 Price Approvals
**Path**: Sales > Price Approvals (`/price-approvals`)

- When a sale is below the minimum price, it requires approval
- View pending approvals and approve/reject them
- All approvals are logged for audit

---

## 4. POS (Point of Sale)

### 4.1 Starting a POS Session
**Path**: POS > Session (`/pos/session`)

1. Click **Open Session**
2. Count and enter the opening cash float
3. The session is now active

### 4.2 POS Billing
**Path**: POS > Billing (`/pos`)

1. Select a customer (or use walk-in)
2. Scan or search for products to add to cart
3. Adjust quantities as needed
4. The cart auto-calculates totals and tax
5. Click **Charge** to complete the sale
6. Choose payment method(s): Cash, Card, Bank, Mobile, Cheque
7. Print the receipt (80mm thermal or A4)

### 4.3 Held Bills
- During billing, you can **Hold** a bill to serve another customer
- Resume held bills from the held bills list

### 4.4 Closing a Session
1. Go to POS > Session
2. Count and enter closing cash
3. The system shows expected vs. actual cash
4. Click **Close Session** to finalize
5. A session summary is generated showing total sales, cash, and variance

### 4.5 Offline Queue
**Path**: POS > Offline Queue (`/pos/offline-queue`)

- Bills created while offline are queued here
- Click **Sync** to upload them when back online
- Duplicate bills are automatically detected and skipped

---

## 5. Inventory Management

### 5.1 Products
**Path**: Inventory > Products (`/products`)

- Add products with: SKU, name, category, unit, cost price, sale price, tax rate
- Set reorder level for low stock alerts
- Track stock enabled/disabled per product
- View current stock levels across warehouses

### 5.2 Stock Valuation
**Path**: Inventory > Stock Valuation (`/stock`)

- View current stock quantity and value for each product
- Valuation uses WAC (Weighted Average Cost) by default
- Filter by warehouse or product

### 5.3 Warehouses
**Path**: Inventory > Warehouses (`/warehouses`)

- Add warehouse/store locations
- Each warehouse tracks its own stock
- Used for multi-branch transfers

### 5.4 Stock Transfers
**Path**: Inventory > Transfers (`/transfers`)

- **Same-day transfer**: Quick transfer between warehouses
- **In-transit transfer**: For multi-day transfers:
  1. **Dispatch**: Stock leaves source warehouse (goes to in-transit)
  2. **Receive**: Stock arrives at destination warehouse
- Track in-transit transfers at Transfers > In-Transit

### 5.5 Stock Adjustments
**Path**: Inventory > Adjustments (`/adjustments`)

- Adjust stock quantities for damage, loss, or physical count corrections
- Choose adjustment type (in or out)
- Enter reason for audit trail
- Posts to GL automatically

---

## 6. Purchases

### 6.1 Suppliers
**Path**: Purchases > Suppliers (`/suppliers`)

- Add suppliers with contact details and tax number
- View supplier balance (payables)

### 6.2 Purchase Invoices
**Path**: Purchases > Purchases (`/purchases`)

- **Create Purchase**: Click "New Purchase"
- Select supplier, add products, quantities, costs
- **Post Purchase**: Finalizes the purchase:
  - Generates purchase number
  - Posts to GL (AP, Inventory, Tax)
  - Updates stock (increases inventory)

### 6.3 Purchase Orders
**Path**: Purchases > Purchase Orders (`/purchase-orders`)

- Create POs to order from suppliers
- Convert PO to Goods Receipt when stock arrives
- Partial receipts supported

### 6.4 Goods Receipts (GRN)
**Path**: Purchases > Goods Receipts (`/goods-receipts`)

- Record goods received from suppliers
- Can be created from a PO or standalone
- Convert GRN to a purchase invoice

### 6.5 Landed Cost
**Path**: Purchases > Landed Cost (`/landed-cost`)

- Allocate additional costs (freight, customs, insurance) to purchases
- Allocation methods: by value, by quantity, or manual
- Recalculates product cost after allocation

### 6.6 Supplier Payments
**Path**: Purchases > Supplier Payments (`/supplier-payments`)

- Record payments to suppliers
- Click "New Payment" to create a payment
- Supports full, partial, and advance payments
- Allocate payments to specific purchase invoices

### 6.7 Purchase Returns
**Path**: Purchases > Purchase Returns (`/purchase-returns`)

- Process returns to suppliers
- Creates stock reduction and GL reversal

---

## 7. Accounting

### 7.1 Chart of Accounts
**Path**: Accounting > Chart of Accounts (`/accounts`)

- View all GL accounts organized by type (Asset, Liability, Equity, Income, Expense)
- Add new accounts
- Group accounts (parent-child) for reporting

### 7.2 Journal Entries
**Path**: Accounting > Journal Entry (`/journals/create`)

- Manual journal entries for adjustments
- Must be balanced (total debits = total credits)
- Supports party (customer/supplier) tagging on AR/AP lines

### 7.3 General Ledger
**Path**: Accounting > General Ledger (`/ledger`)

- View all journal entries
- Filter by account, date range, or reference
- Drill down to individual entries

### 7.4 Period Close
**Path**: Accounting > Period Close (`/period-close`)

- Close accounting periods to prevent further postings
- **Day Close**: Lock a specific day
- **Month Close**: Lock an entire month
- **Quarter Close**: Lock a quarter
- **Year Close**: Lock the fiscal year
- Closed periods block all postings (invoices, journals, etc.)

### 7.5 Fiscal Years
**Path**: Accounting > Fiscal Years (`/fiscal-years`)

- Create and manage fiscal years
- Set start/end dates
- Open or close fiscal years

### 7.6 Year-End Close
**Path**: Reports > Year-End Close (`/reports/year-end-close`)

- Close the fiscal year at year end
- Transfers net income to retained earnings
- Locks the year from further postings

---

## 8. Banking

### 8.1 Bank Accounts
**Path**: Banking > Bank Accounts (`/bank-accounts`)

- Add bank accounts with opening balances
- View current balance per account
- Each account links to a GL account

### 8.2 Transactions
**Path**: Banking > Transactions (`/bank-transactions`)

- View all bank transactions (deposits, withdrawals, transfers)
- Filter by account, date, or type

### 8.3 Expenses
**Path**: Banking > Expenses (`/expenses`)

- **Create Expense**: Click "New Expense"
- Select bank account, payee, expense category
- Enter amount and date
- Posts to GL automatically (expense account + bank account)

### 8.4 Bank Reconciliation
**Path**: Banking > Reconciliation (`/bank-accounts/reconciliation`)

- Reconcile bank statements with system records
- Mark transactions as cleared
- Shows reconciled vs. statement balance

### 8.5 Statement Import
**Path**: Banking > Statement Import (`/bank-statements/import`)

- Import bank statements from CSV files
- Auto-matches transactions where possible

### 8.6 Cheque Deposits
**Path**: Banking > Cheque Deposits (`/cheque-deposits`)

- Group undeposited cheques for bank deposit
- Records the deposit in the bank account

---

## 9. Reports

### 9.1 Sales Report
**Path**: Reports > Sales Report (`/reports/sales`)

- Period presets: Daily, Weekly, Monthly, Quarterly, Half-Yearly, Yearly, Custom
- Group by: Day, Week, Month, Customer, Product, Salesperson
- Shows: Invoices count, Subtotal, Tax, Grand Total, Gross Profit, Outstanding
- Detailed breakdown table and recent invoices

### 9.2 Profit & Loss (Income Statement)
**Path**: Reports > Profit & Loss (`/reports/profit-and-loss`)

- Shows revenue, COGS, expenses, and net income
- Select date range
- Comparative view with prior periods

### 9.3 Balance Sheet
**Path**: Reports > Balance Sheet (`/reports/balance-sheet`)

- Shows assets, liabilities, and equity
- As of a specific date
- Comparative view available

### 9.4 Cash Flow
**Path**: Reports > Cash Flow (`/reports/cash-flow`)

- Shows cash inflows and outflows
- Operating, investing, and financing activities

### 9.5 Trial Balance
**Path**: Reports > Trial Balance (`/trial-balance`)

- Lists all accounts with debit/credit balances
- Total debits must equal total credits
- Useful for verifying balanced books

### 9.6 VAT Registers
**Path**: Reports > VAT Registers (`/reports/vat-registers`)

- Sales VAT (output tax) and Purchase VAT (input tax)
- Filter by period
- Shows VAT payable/receivable

### 9.7 AR/AP Aging
**Path**: Reports > AR/AP Aging (`/reports/aging`)

- Aging buckets: Current, 1-30, 31-60, 61-90, 90+ days
- Shows outstanding receivables and payables
- Identify overdue invoices and bills

### 9.8 Gross Profit
**Path**: Reports > Gross Profit (`/reports/gross-profit`)

- Gross profit by product, category, or period
- Shows margin percentage

### 9.9 Profit Analytics
**Path**: Reports > Profit Analytics (`/reports/profit-analytics`)

- Profit analysis by product, customer, or salesperson
- Identify most profitable segments

### 9.10 Dead & Slow Stock
**Path**: Reports > Dead & Slow Stock (`/reports/dead-slow-stock`)

- Identifies products that haven't sold in a long time
- Categories: Dead (never sold), Slow (sold but long ago)
- Helps with inventory cleanup decisions

### 9.11 Customer Statement
**Path**: Reports > Customer Statement (`/reports/customer-statement`)

- Statement of account for a specific customer
- Shows invoices, payments, and running balance
- Can be sent to customers

---

## 10. Setup & Administration

### 10.1 Company Settings
**Path**: Setup > Company (`/company`)

- Edit company name, address, tax number, currency
- Set fiscal year start
- Configure date format (AD or BS — Nepali calendar)

### 10.2 Branches
**Path**: Setup > Branches (`/branches`)

- Create branches for multi-location operations
- Each branch can have its own warehouses

### 10.3 Users
**Path**: Setup > Users (`/users`)

- Create user accounts for staff
- Assign roles to users
- Each user belongs to a company and optionally a branch

### 10.4 Roles & Permissions
**Path**: Setup > Roles (`/roles`)

- Create roles (e.g., Accountant, Cashier, Manager)
- Assign granular permissions per role
- Permissions control access to modules and actions

### 10.5 Settings
**Path**: Setup > Settings (`/settings`)

- Configure currency, decimal places
- Set date format (AD/BS)
- Configure tax rates
- Set invoice numbering format

### 10.6 Subscription
**Path**: Setup > Subscription (`/settings/subscription`)

- View current subscription plan
- See features included
- Upgrade/downgrade plans

### 10.7 Import / Export
**Path**: Setup > Import / Export (`/settings/import-export`)

- Import data from CSV files (products, customers, suppliers)
- Export data to CSV/Excel

### 10.8 API Tokens
**Path**: Setup > API Tokens (`/settings/api-tokens`)

- Generate API tokens for third-party integrations
- Revoke tokens when no longer needed

### 10.9 Audit Trail
**Path**: Setup > Audit Trail (`/audit`)

- View all system actions (create, update, delete)
- Filter by user, date, or action type
- Full audit log for compliance

---

## 11. Backups & Google Drive Sync

### 11.1 Backup Management
**Path**: Setup > Backups (`/backups`)

### Creating a Backup
1. Click **Create Backup**
2. Confirm the action
3. The system creates a gzipped SQL dump of the entire database
4. The backup appears in the list with size and date

### Downloading a Backup
- Click **Download** next to any backup file
- The file downloads as a `.sql.gz` file

### Deleting a Backup
- Click **Delete** next to a backup
- Confirm the deletion

### 11.2 Google Drive Sync
Once Google Drive is connected (see SETUP.md for configuration):

1. **Connect**: Click "Connect Google Drive" and authorize
2. **Auto-sync toggle**: When enabled, every backup is uploaded to Google Drive automatically
3. **Real-time backup**: When enabled, a backup is created after every change (invoices, purchases, journals, etc.) and uploaded to Drive
   - A 2-minute quiet period applies — rapid changes produce one backup, not many
   - Requires a queue worker running (`php artisan queue:work --queue=backups`)

### 11.3 Restoring from Backup
```powershell
# Extract the gzip
gunzip backup_erp_2026-08-25_023930.sql.gz

# Import to database
mysql -u root -p erp < backup_erp_2026-08-25_023930.sql
```

---

## 12. Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Alt + D` | Go to Dashboard |
| `Enter` | Confirm dialog / submit form |
| `Esc` | Close modal/dialog |

---

## 13. Mobile Usage

The ERP is mobile-friendly and works on phones and tablets:

### Sidebar
- Tap the **hamburger icon** (three dashes) in the top-left to open the sidebar
- Tap the **X** inside the sidebar or tap outside to close it
- Nav groups are collapsible — tap a group label to expand/collapse

### Tables
- Tables scroll horizontally on small screens
- Swipe left/right to see all columns

### Forms
- Forms are responsive and stack vertically on mobile
- All inputs are touch-friendly

### POS
- POS billing works on tablets (recommended for counter use)
- Touch-friendly product search and cart

---

## 14. FAQ

### Q: How do I cancel a posted invoice?
A: Go to Sales > Invoices, find the invoice, and click "Cancel". Enter a reason. The system creates a reversal entry — the original invoice remains for audit but is marked as cancelled.

### Q: Can I edit a posted invoice?
A: No. Posted financial documents are immutable (this is an accounting standard). To correct an error, cancel the invoice and create a new one.

### Q: How do I close a month to prevent further entries?
A: Go to Accounting > Period Close, select the "Month" tab, and close the desired month. No postings will be allowed to that month afterward.

### Q: How does stock costing work?
A: The system uses WAC (Weighted Average Cost) by default. Each time stock is received, the average cost is recalculated. COGS is calculated at the WAC rate when stock is sold.

### Q: How do I switch between companies?
A: If you're a platform admin, use the company dropdown in the top bar. Select a company to view its data.

### Q: Why are some sidebar sections hidden?
A: Sidebar sections are controlled by your subscription plan features and your role permissions. Contact your administrator to upgrade the plan or adjust your permissions.

### Q: How do I record a customer payment?
A: Go to Sales > Receipts, click "New Receipt", select the customer, enter the payment amount and method, and allocate it to invoices.

### Q: How do I record an expense?
A: Go to Banking > Expenses, click "New Expense", select the bank account and expense category, enter the amount, and save.

### Q: How do I see how much a customer owes me?
A: Go to Reports > AR/AP Aging for a summary, or Reports > Customer Statement for a detailed statement for a specific customer.

### Q: How do I back up my data?
A: Go to Setup > Backups and click "Create Backup". For automatic backups, enable Google Drive sync and/or set up scheduled backups (see SETUP.md).

### Q: What happens if the internet goes down while using POS?
A: POS bills created while offline are stored in the Offline Queue. When back online, go to POS > Offline Queue and click "Sync" to upload them.

### Q: How do I change my password?
A: Contact your system administrator. They can reset your password from Setup > Users.

---

## Support

For technical support, contact your system administrator or refer to the SETUP.md file for configuration and troubleshooting.
