Page Specifications

1. Dashboard

KPI StatCards (5)

Displayed in a horizontal row at the top. Each card shows a primary metric value, label, and comparison to the previous period.

1. Today's Sales — total billing amount for today
2. Today's Collections — total payments received today
3. Total Outstanding — sum of all farmer dues
4. Bills Today — count of bills created today
5. Active Farmers — farmers with at least one bill in the last 90 days

Toggleable Widgets (10)

Each widget can be shown/hidden via a gear icon. State persisted in dealer preferences.

1. Sales Trend — line chart of daily sales for last 30 days (Recharts)
2. Top Products — bar chart of top-selling products by quantity
3. Overdue Farmers — list of farmers with overdue payments, sorted by amount
4. Recent Bills — last 5 bills with farmer name, amount, status
5. Low Stock — products below reorder point
6. Expiring Stock — lots expiring within 30 days
7. Payment Methods — pie chart breakdown (cash/UPI/bank/cheque)
8. Branch Comparison — sales comparison across branches (if multi-branch)
9. Monthly Summary — month-to-date sales, collections, purchases
10. Quick Actions — shortcut buttons for common actions

Layout

• Desktop: KPI cards in a single row. Widgets in a 2-column grid below.
• Mobile: KPI cards as a horizontal scroll. Widgets stack vertically.

2. New Bill

Mobile Layout (3 Steps)

Desktop Layout (2 Panels)

• Left panel: FarmerSelector at top, ProductSelector below. Sidebar collapses to 76px to give maximum space.
• Right panel: Running bill summary, payment inputs, review. Always visible alongside product selection.

Draft Tabs

Up to 5 concurrent drafts stored in sessionStorage. Tab bar at top of billing page. Each draft preserves: selected farmer, added products with quantities, and payment info. Allows switching between partial bills when interrupted.

Keyboard Shortcuts

Empty State

If no products are configured yet, shows a prompt to "Add your first product" with a link to inventory setup.

3. Farmer Ledger

Tabs

• Ledger — Chronological list of all transactions (bills, payments, returns, adjustments). Infinite scroll with paginated RPC. Each entry shows date, type, amount, running balance.
• Items — Products purchased by this farmer with quantities and totals.
• Discounts — Per-product discount rates configured for this farmer.

Actions

• Collect Payment (opens payment flow with farmer pre-selected)
• Create Bill (opens billing with farmer pre-selected)
• Share Statement (WhatsApp or PDF)
• View Statement (formatted printable view)
• Edit Farmer (profile details)

Layout

• Desktop: Farmer summary card at top (name, phone, outstanding, credit limit). Tabs below with full-width table.
• Mobile: Farmer summary as compact header. Tabs as swipeable. Ledger entries as cards instead of table rows.

4. Farmer List

Searchable, filterable list of all farmers. Search by name or phone number. Filter by: outstanding balance range, last bill date, active/inactive status. Sort by: name, outstanding amount, last activity. Pagination: server-side with page size of 20.

Empty state: "No farmers yet. Add your first farmer to get started" with an "Add Farmer" button.

5. Inventory

Product list with current stock levels. Each row shows: product name, category, current stock quantity, unit, latest rate, total stock value. Search by product name. Filter by category, stock status (in stock, low stock, out of stock). Color-coded stock indicators: green (adequate), yellow (low), red (out of stock).

6. Inventory Detail

Sections

• Product Summary: Name, category, current stock, average cost, latest selling rate, MRP
• Active Lots: Table of FIFO lots — purchase date, quantity remaining, cost per unit, expiry date, supplier. Sorted oldest first.
• Movement History: All stock movements for this product — purchases, sales, returns, transfers, adjustments. Filterable by type and date range.
• Rate Adjustment: Change selling rate per lot with reason tracking. Creates audit entry in movements.

Actions

• Record Purchase (opens purchase form pre-filled with this product)
• Adjust Rate (change selling rate with reason)
• Stock Adjustment (manual correction with reason)
• View by Branch (if multi-branch, toggle stock view per branch)

7. Reports

Date Presets

All reports support: Today, Yesterday, This Week, This Month, Last Month, This Quarter, This Year, Custom Range.

Report Sections

• Sales Register — Every bill with line items, grouped by date
• Profit Report — Revenue minus cost of goods sold, per product
• Stock Report — Current stock levels, valuation, expiring items
• Dues Report — Farmer-wise outstanding with ageing
• Collection Report — Payments received, grouped by method
• Purchase Report — Supplier-wise purchases
• GST Report — Tax breakdown for filing

Export Formats

PDF (via jsPDF) and Excel-compatible CSV. Reports open in a printable view for direct browser printing.

8. Daily Book

Sub-pages (11)

1. Summary — Day overview with totals for all categories
2. Bills — All bills created on the selected date
3. Payments — All payments received
4. Purchases — All stock purchases
5. Supplier Payments — Payments made to suppliers
6. Returns — All returns processed
7. Expenses — All expenses recorded
8. Cash Entries — Manual cash book entries
9. Stock Transfers — Inter-branch transfers
10. Adjustments — Stock and rate adjustments
11. Cancellations — Cancelled bills

Key Behaviors

• Date navigation: Left/right arrows to move between days. Date picker for jumping to specific date.
• Prefetching: Adjacent days (yesterday and tomorrow) are prefetched for instant navigation.
• Empty state: "No activity on this date" with option to navigate to nearest active date.

9. Settings

Settings Sections

• Shop Profile — Shop name, address, phone, logo, GSTIN, PAN
• Lock Screen — Auto-lock timeout, PIN configuration
• Billing Templates — Choose from 5 invoice designs (TemplateOne through TemplateFive). Configure which columns to show: HSN code, rate, discount, GST breakdown, MRP, expiry date, signature area. Branch-specific template selection.
• Feature Badges — Visual indicators for enabled features on the plan
• WhatsApp — Configure authkey.io API key, manage templates, view message quota
• Branches — Add/edit branches (if multi-branch enabled)
• Staff — Manage staff members (if staff access enabled)
• Subscription — View current plan, upgrade, manage billing

10. Dues

Ageing Buckets

Farmers grouped by how long their dues have been outstanding:

• 0–30 days — Current dues (normal)
• 31–60 days — Overdue (yellow)
• 61–90 days — Significantly overdue (orange)
• 90+ days — Critical (red)

Key Behaviors

• Virtualized list: Uses windowed rendering for performance with 500+ farmers
• Click farmer to open ledger
• "Collect Payment" action per farmer row
• "Send Reminder" via WhatsApp per farmer
• Sort by: amount, name, age of oldest due
• Summary card at top: total outstanding, number of farmers with dues

11. Cashbook

Daily cash register view. Shows opening balance, all cash movements (sales, payments received, purchases, expenses, manual entries), and closing balance. Date navigation with prefetching. Manual entry option for corrections. Linked to all bill and payment transactions via cash_book table.

12. Expenses

Expense tracking with categories (rent, transport, salary, utilities, misc). Each expense: date, amount, category, description, payment method. List view with date filters and category filters. Monthly summary chart. Totals by category. Creates entries in cash_book when payment method is cash.

13. Suppliers

Supplier List

All suppliers with name, phone, outstanding balance. Search and sort.

Supplier Detail / Ledger

Similar to Farmer Ledger but for supplier transactions: purchases, payments made. Running balance. Actions: Record Purchase, Make Payment, View Statement.

14. Bill History

Searchable list of all bills. Search by bill number, farmer name. Filter by: date range, status (active, cancelled, edited), payment status (paid, partial, unpaid), branch. Sort by date, amount, farmer name. Pagination with server-side cursor. Each row: bill number, date, farmer, amount, paid, status badges.

15. Bill Detail

Display

Renders the bill using the configured invoice template (TemplateOne through TemplateFive). Shows: bill number, date, farmer details, line items with quantities/rates/amounts, subtotal, discounts, GST breakdown (if applicable), total, payment received, balance due, signature (if captured).

Actions

• Edit — Opens /billing/:id/edit. Requires billEditing feature gate.
• Cancel — Same-day only, unpaid only. Confirmation dialog. Calls cancel_bill_v1 RPC.
• Return — Opens /billing/:id/return. Requires returns feature gate.
• Share via WhatsApp — Sends bill notification via authkey.io or opens wa.me link.
• Download PDF — Renders bill to PDF via html2canvas (DOM → canvas → PNG → PDF).
• Print — Opens browser print dialog with the invoice template.
• Collect Payment — If balance due > 0, opens payment flow pre-filled with this bill's farmer and remaining amount.