Personas & Workflows

Verified Against source code Last updated: September 2026

Dealer (Owner)

Authentication

Method: Supabase Auth — email + password
Session: JWT-based, managed by Supabase client SDK
Entry point: /login
Registration: /register → 4-step onboarding wizard
Password reset: /forgot-password via Supabase Auth email

Access Level

Full access to all features. The dealer is the account owner and has unrestricted access to:

All billing, inventory, and financial features
Staff management — create, edit, disable staff accounts
Branch management — create branches, assign staff
Profit and cost data (hidden from staff by default)
Settings — shop profile, billing templates, integrations
Subscription management

Daily Activity Profile

Bills per day: 5–20
Payments collected per day: 2–10
Purchases per week: 2–5
Primary device: Mobile (70%+ of sessions)

Staff Member

Authentication

Method: PIN-based login (4+ digit PIN)
PIN storage: bcrypt hashed via trg_staff_hash_pin trigger
Session: staff_sessions table with SHA-256 hashed tokens
Entry point: /:shopSlug/:branchSlug/staff
Context RPC: staff_portal_context_v2 — resolves shop/branch from URL slugs
Rate limiting: staff_login_attempts table tracks failed attempts

Branch Scoping

Each staff member is assigned to one or more branches via branch_ids UUID[] on the staff_members table. Staff can only see and create data within their assigned branches. The branch context is set on login and cannot be changed without re-authenticating.

Permissions (JSONB)

Staff permissions are stored as a JSONB object on staff_members.permissions. Each key maps to a module and the value is either "visible" or "hidden".

Permission Key	Module	Default
`dashboard`	Dashboard	visible
`billHistory`	Bill History	visible
`newBill`	Create New Bill	visible
`farmerList`	Farmer List	visible
`addFarmer`	Add New Farmer	visible
`inventory`	Inventory / Stock	visible
`suppliers`	Suppliers	hidden
`cashbook`	Cashbook	hidden
`expenses`	Expenses	hidden
`reports`	Reports	hidden
`settings`	Settings	hidden
`branches`	Branch Management	hidden
`staffManagement`	Staff Management	hidden
`transactions`	Transaction History	hidden

Important: Permissions are enforced client-side only. The RLS (Row Level Security) policies grant full data access for the staff member's dealer. A technically savvy staff member could bypass these restrictions via direct API calls.

Platform Admin

Authentication

Method: Separate auth system (not Supabase Auth)
Session: admin_sessions table with SHA-256 hashed tokens
Entry point: /admin/login
Layout: Separate AdminLayout component, completely isolated from dealer UI
Rate limiting: None on admin login

Roles

Role	Capabilities
`superadmin`	Full platform access — manage all dealers, subscriptions, product catalog, broadcasts, audit logs, admin users
`admin`	Manage dealers, subscriptions, support tickets, product catalog
`support`	View dealers (read-only), manage support tickets, impersonate dealers (read-only)

Admin Capabilities

Dealer management: View all registered dealers, their subscription status, usage metrics
Subscription management: Extend trials, upgrade/downgrade plans, manage billing
Impersonation: Read-only view of any dealer's account for debugging and support
Product catalog: Manage the master product catalog that dealers can import from
Broadcasts: Send announcements to all dealers or filtered segments
Audit logs: View all admin actions with timestamps and actor
WhatsApp addon plans: Manage WhatsApp message quota plans and pricing

Key Workflows

1. Creating a Bill

The core workflow. On mobile it's a 3-step wizard; on desktop it's a 2-panel layout. Both converge on the same save logic.

Select Farmer — Search by name or phone. The FarmerSelector component shows recent farmers first, with a search field. If the farmer doesn't exist, QuickAddFarmerModal allows inline creation without leaving the bill flow.

Select Products — The ProductSelector component (1,519 lines) shows the dealer's product catalog. Search, filter by category. For each product: enter quantity, confirm rate (auto-filled from latest lot), apply per-farmer discount if configured. Products are added to the bill items list. Up to 5 concurrent draft tabs in sessionStorage for switching between partial bills.

Payment & Review — The PaymentStep shows the bill total. Enter payment amount (can be 0 for full credit, partial, or full). Select payment method (cash, UPI, bank transfer, cheque). The ReviewStep shows a summary. Optional: capture signature on canvas.

Save — Calls create_bill_v2 RPC. This is an atomic PostgreSQL function that in a single transaction: creates the bill record, inserts bill items, deducts stock from FIFO lots, records payment (if any), allocates payment to the bill, creates cash book entry, updates farmer due balance. On success, the user is shown the bill detail with options to share via WhatsApp or download PDF.

2. Collecting a Payment

Select Farmer — Navigate to farmer's ledger or use the "Collect Payment" action from the dues page.

Enter Amount — Enter the payment amount. The farmer's current outstanding balance is displayed for reference.

Choose Method — Select payment method: Cash, UPI, Bank Transfer, or Cheque.

Allocate to Bills — The system allocates the payment to the farmer's oldest unpaid bills first (FIFO). The user can also manually allocate to specific bills. Settlement discounts can be applied during allocation.

Confirm — Payment is recorded, farmer due balance is updated, cash book entry is created. A payment receipt can be shared via WhatsApp.

3. Morning Routine

Check Dashboard — Review 5 KPI cards: today's sales, collections, outstanding dues, number of bills, active farmers. Scan the 10 toggleable widgets for alerts and trends.

Review Dues — Open the Dues page to see farmers sorted by outstanding amount. Focus on the ageing buckets — 90+ day dues need immediate attention.

Plan Collections — Identify farmers to visit or call. Use WhatsApp due reminders to send automated reminders to farmers with overdue balances.

4. End of Day

Review Daily Book — Navigate to the Daily Book page and review all transactions for the day: bills created, payments received, purchases made, expenses recorded.

Close Cash — Check the Cashbook for today. Verify the closing balance matches the physical cash. Record any discrepancies.

Reconcile — Confirm all payments are recorded, all bills are accounted for. The Daily Book's summary view shows totals for each category.

Persona Comparison Matrix

Dimension	Dealer (Owner)	Staff Member	Platform Admin
Auth method	Email + password (Supabase Auth)	4+ digit PIN (bcrypt)	Email + password (custom)
Session storage	JWT (Supabase SDK)	`staff_sessions` table	`admin_sessions` table
Entry URL	`/login`	`/:shopSlug/:branchSlug/staff`	`/admin/login`
Data scope	All own dealer data	Assigned branch(es) only	All dealers (platform-wide)
Rate limiting	Supabase default	`staff_login_attempts`	None
Permission model	Full access	14-key JSONB (client-side)	Role-based (superadmin/admin/support)
Can create bills	Yes	Yes (if `newBill` = visible)	No
Can manage staff	Yes	No (unless granted)	No
Can view profit	Yes	No	Yes (impersonation)