Nickson CRM — the operations manual for every role at Jagdish Industries.

A ten-minute orientation. Where to sign in, how to install the console on your phone, what the screen chrome does, and who sees what.

1.1Access & login

The console lives at https://crm.nicksonpumps.com. Two sign-in methods, both fronted by the same /login screen with a tab switcher:

• Email + password — the default for all salaried staff and admins.
• Phone + WhatsApp OTP — for shop-floor workers and temporary hires. Enter a 10-digit Indian mobile, receive a 6-digit code on WhatsApp, log in. First-time OTP sign-in silently mints a User account and links it to the worker record — no ticket to IT required.

Forgotten passwords go through the standard reset link on the login form. Ask HR if the reset email doesn't arrive.

1.2Install as a phone app

The console is a Progressive Web App. Once installed it opens fullscreen like a native app, works offline for the login shell, and supports push notifications on Android.

• Android · Chrome / Edge / Brave. Menu (⋮) → Install app. Or wait for the floating Install Nickson CRM pill at the bottom of the screen.
• iPhone · Safari. Share (□↑) → Add to Home Screen. Note iOS does not support push notifications for PWAs.
• Desktop. Look for the install icon (⊕) in the URL bar or menu → Install Nickson CRM.

1.3Interface tour

Sidebar

Grouped by function. What you see depends on your role — a sales rep sees leads, dealers, catalog, commerce; HR sees HR and payroll; the owner sees everything. Collapse the sidebar via the arrow at the bottom-left when the workstation monitor is short on horizontal room.

Command palette · ⌘K / Ctrl+K

Fastest way to jump anywhere. Type a record identifier, a page name, or a customer name — hit enter, land on the record. Faster than clicking through the sidebar for anything a user does more than twice a day.

Top bar

• QR scanner. Scan a pump serial sticker, a package label, a vendor code, or a dealer QR. Camera permission asked once, then it's a one-tap lookup.
• Quick capture. One-tap add of a new lead, task, or note.
• Notifications. Inbox of things needing your attention — pending approvals, overdue tasks, new lead assignments, warranty claims raised.
• Language. English · हिन्दी · ਪੰਜਾਬੀ. Cookie-scoped, applies to the whole console.

1.4Roles & permissions

Every user carries one role. The role controls which sidebar sections appear, which pages open, which actions are allowed, and — critically — which rows are visible. A sales rep sees their team's leads, not other teams'. A worker sees only their own payslip. Row-level security is enforced at the database boundary, not on the frontend.

Every function of the business, one card per module. Skim the grid for orientation, dive into a section for the fields, screens, and integrations that come with each.

The seventeen

Each role's daily rhythm mapped to the console. Not everything on the list, every day — the load-bearing beats that keep the operation moving.

Six real scenarios using the seeded data. Real names, real values to type, real screens to expect. If you've never used the console before, work through these end-to-end — you'll understand the whole thing.

Aggregations that turn day-in day-out entries into decisions. One dashboard per role, plus a year-end pack for the CA.

Year-end pack for the CA

Exports to hand your Chartered Accountant at financial year end:

• /commerce/invoices?fromDate=&toDate= — GST-invoiced sales (CSV export).
• /procurement/vendor-invoices?fromDate=&toDate= — GST-invoiced purchases (CSV).
• /finance/cash-register?from=&to= — non-GST cash movements, tagged by legal reason.
• /finance/payments?fromDate=&toDate= — payments log.
• /finance/msme — MSME 45-day compliance report.
• /hr/payroll/payslips?year= — annual payroll summary.

Compliance guardrails, the URL directory, test credentials, and where to shout when something's off.

6.1Compliance guardrails

Automatic protections the console enforces. You don't have to remember them — the system asks the right question before you save.

6.2URL directory

6.3Test credentials

Nine test logins are seeded on prod. All share password TestPass123!. Rotate before you'd hand these to anyone real — they exist for staff walkthroughs and demos.

6.4Support

• Business owner · Rahul Singh — rahulsingh0893450@gmail.com · +91 98772-69207
• Developer · Tarun Bhardwaj — itarunbhardwaj@gmail.com
• CRM issues & feedback — file a ticket at /helpdesk/tickets/new with category set to internal.

Every meaningful dropdown, radio, and status enum in the console — what each value means, when to reach for it, why it matters, and the common mistake to avoid.

7.1Sales & Leads

Lead stage

Every lead lives in one stage at a time. The whole daily kanban lives off this field.

Lead source

Where the lead came from. Drives attribution reports + which team owns the follow-up SLA.

7.2Products

Product status

Stock valuation method

Set per product. Governs how the average cost is computed as receipts land.

Warranty start

7.3Procurement

Vendor type

Vendor status

Vendor onboarding stage

Independent from status — this is the paperwork progress.

GRN purchase type

The critical distinction — what kind of receipt this is. Set at GRN creation and never mutated.

Cash-purchase payment mode

Shared enum used across cash-purchase GRN and Cash Register.

QC decision (per GRN line)

7.4Manufacturing

Stock Entry purpose

The most consequential enum in the system — each value posts differently to the stock ledger.

BOM status

Piece-rate operation kind

7.5Inventory

Warehouse type

Set once at warehouse creation. Governs which downstream flows can send stock in and out.

Reorder method

7.6HR & Payroll

Employment status

Employment type

Attendance punch type

7.7Finance & Cash Register

Cash Register direction

Cash Register nature

The specific kind of movement. Scoped by direction — Money in options differ from Money out.

Cash Register exemption reason · the deepest reference

The mandatory field. Every entry needs one. The year-end CA pack uses this to split records into ITR / GSTR / non-income buckets.

7.8Warranty

Warranty claim status

Claim issue type

7.9Notifications

Announcement audience

Notification channel

Notification priority

The console isn't just a place to store records. Every workflow it runs is a lever — to grow revenue, reduce cost, speed operations, retain customers, protect against statutory risk, empower the team, or give the owner clarity. Here's the full inventory. For the important ones: what the old way looks like, what the console actually does, the impact, how to get the most out of it, and why this stack is worth bragging about.

8.1Grow revenue

Top-of-funnel to booked order. Every workflow here is about turning inquiries into rupees faster than the competition can.

8.2Reduce cost

Every rupee saved on procurement or inventory is a rupee that hits the bottom line without needing a new sale.

8.3Speed up operations

Making pumps faster, with fewer disputes, with better traceability — every hour saved on the floor is an hour of extra capacity.

8.4Retain customers

A pump lasts 5-10 years; a customer relationship should last longer. Retention starts with knowing every pump you've shipped and every service call it's been on.

8.5Compliance shield

This is where a well-designed CRM saves you money you don't even know you're at risk of losing. Every one of the workflows below has a specific penalty attached — the console makes sure you don't step on any of them.

8.6Empower workers

Retention beats hiring. Shop-floor staff who feel seen — who can check their own attendance and earnings on their phone — stay longer and work better.

8.7Owner clarity

Rahul walking into the office Monday morning should know, in five minutes, everything that moved over the weekend. Every workflow below buys back time and attention.

The whole point, on one line

The Nickson console gives a small pump manufacturer in Amritsar the same operational sophistication a ₹500 crore enterprise buyer would expect from SAP or Oracle, at a fraction of the cost, in a UI shop-floor staff actually use, with statutory guardrails specific to the Indian tax code, in three languages, on any phone. That's the pitch. Everything above is proof.

The exhaustive form guide. Every field on every form gets a line — what it is, whether it's required, what to type, and the mistake to avoid. Read it end-to-end once as an admin; return to it as a lookup when a specific field is confusing. Legend: req mandatory · opt optional · italic-highlighted indicates a specific value or default.

You just got your admin credentials. This is what to do in order — from the first thirty minutes to the year-end pack. No thinking required; follow the checkboxes.

10.1Your first 30 minutes

1. Sign in at https://crm.nicksonpumps.com/login with the credentials you were given. 2 min
2. Change your password immediately — top-right avatar → Profile → change password. Don't leave the default. 2 min
3. Install the PWA on your phone (Chrome / Edge → Install app) and your desktop. See Part I § 1.2. 3 min
4. Take the interface tour — read Part I § 1.3 and click through the sidebar sections your role shows. 5 min
5. Try the command palette — press CtrlK (or ⌘K on Mac). Type "dealers", "leads", "cash register" — jump around. 3 min
6. Open the Owner Brief at /dashboards/owner. Read yesterday's tiles. This is your Monday-morning ritual. 5 min
7. Read Part VIII (Every workflow & how it grows the business) to understand what the CRM is actually for. 10 min

10.2Week 1 goals

By end of week 1, you want: real users onboarded, real master data verified, and one real end-to-end order flowing through.

1. Open /hr/departments — verify the 8 seeded departments match Nickson's org (Production, Quality, Dispatch, Sales, Accounts, HR, Procurement, Maintenance).
2. Open /hr/designations — verify the 12 seeded designations. Add / rename as needed.
3. Open /inventory/warehouses — verify 7 seeded warehouses exist (PLANT-MAIN, WH-FG, WH-WIP, WH-SPARES, WH-RTN, WH-TRANSIT, WH-SCRAP). Correct the addresses if the seed used placeholders.
4. Open /procurement/vendors — 18 industry-real vendors are seeded. Update GSTINs with the real numbers on file. Add any Nickson-specific vendors missing.
5. Open /products — 24 products seeded (12 finished pumps + 12 raw materials). Update prices, images, and specs where the seed used placeholders.

1. Delete or archive the 9 test users (admin@test, sales@test etc.) once you have real replacements ready — or keep them for training.
2. Onboard the first real salaried employee at /hr/employees/new. See Part IX § 9.13 for every field. Result: employee row + User account + welcome email.
3. Onboard the first real wage worker at /hr/wage-workers/new. Phone number is enough — they log in via OTP.
4. Verify the new user can log in — send them the credentials, watch them log in successfully.
5. Onboard the rest of the team following the same pattern.

1. Log the first real lead at /leads/new (Walkthrough 01 in Part IV shows the flow with real values).
2. Handle the first real cash purchase using /procurement/grns/new — this proves the market-run flow works (Walkthrough 02).
3. Post the first real cash-register entry at /finance/cash-register/new to prove the exemption tagging (Walkthrough 03).
4. Convert the first real lead to a quote → sales order (Walkthrough 01 continued).

1. Set reorder rules at /inventory/reorder-rules for the 15-20 most critical raw materials. See Part IX § 9.5 for field reference.
2. Configure integrations — IndiaMART webhook, WhatsApp Cloud API, GST GSP. See Part XII.
3. Set up notification templates for the events that matter to you (Part XVI).
4. Test each integration end-to-end — send a test IndiaMART lead, send a test WhatsApp, generate a test IRN.

10.3Weekly admin rhythm

Rinse and repeat. Small daily habits keep the console healthy.

1. Open the Owner Brief — read every tile.
2. Clear the notification bell — decide, delegate, or defer each item.
3. Review /workflows-admin/approvals — clear pending approvals.
4. Check /inventory/reorder-rules for stockout alerts fired over the weekend.

1. Handle exceptions as they surface — cash-register entries flagged, MSME breaches approaching, warranty claims escalating.
2. Read Daily Call Reports from field reps at end of each day.
3. Review /hr/approvals/daily-work — approve piece-rate submissions.

1. Reconcile the week's cash-register entries with till + bank statement.
2. Confirm no MSME invoices are breaching the 45-day gate over the weekend.
3. Skim the sales dashboard for weekly conversion trends.

10.4Monthly tasks

1. Payroll close · run /hr/payroll/payslips → Generate for period. Spot-check outliers. Trigger bulk payment via /finance/payments.
2. MSME 45-day review · check /finance/msme for any invoices approaching or breaching. Prioritise these in the next payment run.
3. AR aging review · /finance/ar-aging — identify collection calls for anything over 60 days.
4. Vendor performance · review /procurement/vendors scoring — anyone consistently late or QC-failing gets a conversation.
5. Cash Register month-close · review last month's entries with the accountant on the first of each month. Any wrongly-tagged entries get corrected before month-close hardens.
6. Reorder rule review · adjust reorder points based on last month's consumption vs stock-out incidents.
7. Statutory compliance · PF, ESI, TDS payments must be made by prescribed deadlines. Confirm each is done and evidenced.

10.5Quarterly reviews

1. Dealer tier review · promote / demote dealers based on YTD performance. Tier drives auto-pricing.
2. Employee performance reviews · /hr/performance/reviews.
3. Vendor threshold audit · any below-threshold vendor whose cumulative purchases are approaching ₹40 lakh — the console warns, but review proactively.
4. QMS calibration schedules · verify all measuring instruments due for calibration have current certificates.
5. Reorder rule + safety stock rebalance · adjust based on quarterly consumption patterns.
6. Marketing content refresh · product pages, banners, FAQs on /content/*.

10.6Year-end pack for the CA

End of financial year (typically 31 March). Hand your Chartered Accountant these exports:

1. /commerce/invoices?fromDate=&toDate= — GST-invoiced sales (CSV).
2. /procurement/vendor-invoices?fromDate=&toDate= — GST-invoiced purchases (CSV).
3. /finance/cash-register?from=&to= — non-GST cash movements, tagged by legal reason.
4. /finance/payments?fromDate=&toDate= — all payments received + paid.
5. /finance/msme — MSME 45-day compliance report.
6. /hr/payroll/payslips?year= — annual payroll summary.
7. /inventory/stock-balances — closing stock valuation.
8. /assets/depreciation — depreciation schedule for the year.

When something's off — an error message, a permissions puzzle, a page that seems empty when it shouldn't be. Look here first before pinging the developer.

11.1Common error messages

11.2Login & access issues

My phone-OTP isn't arriving.

Check the phone number is in E.164 format (+91 prefix). Confirm WhatsApp is installed and can receive messages on that number. If it's still not arriving, try email login instead — HR can set a temporary password.

I know my password is right but login fails.

Check the User row's active flag. HR can toggle it back on. Also confirm no one accidentally reset the password.

I get redirected in a loop after logging in.

Your role is EMPLOYEE but your User isn't linked to an EmployeeV2 / TemporaryWorker record. Ask HR to link you at /hr/employees/[id] or /hr/wage-workers/[id] (userId field).

Command palette (⌘K) doesn't open.

Some browsers reserve CtrlK — the console-provided combination is CtrlK on Windows / ⌘K on Mac. If it's still not opening, hard-refresh (CtrlShiftR) — service worker might be caching a stale version.

11.3"I know it exists but I can't see it"

I'm looking for a specific lead / order / dealer and it's not in the list.

Row-level security is filtering you. Sales sees their team's leads, not other teams'. Employees see only their own records. Admins see everything. Ask an admin to look up the record, or switch to the ADMIN role temporarily.

The vendor / dealer / customer isn't in the picker.

Status. Only ACTIVE records show in pickers by default. Check /procurement/vendors or /dealers — if it's PROSPECT / INACTIVE / BLACKLISTED, that's why.

My payslip isn't showing at /e/salary.

Payslip hasn't been generated yet for this period, or the daily-work submission hasn't been HR-approved. Check /hr/approvals/daily-work for approval status.

The BOM won't accept item X in the components table.

Item's status is DISCONTINUED or not ACTIVE. Reactivate at /products/[id], or pick an equivalent.

11.4PWA / mobile issues

Install prompt doesn't appear on my phone.

You're already installed (open the app icon), OR the browser cached a "not installable" verdict. Try: hard-refresh, or open in a fresh tab. Some browsers require the site to have been visited for 30 seconds before offering install.

Attendance selfie camera won't open.

Camera permission was denied at some point. Fix: phone Settings → Site permissions → crm.nicksonpumps.com → allow camera. Reload the page.

GPS location not captured on attendance.

Location permission denied. Same fix as camera. Also verify you're outside a heavily shielded factory area where GPS won't lock.

App feels slow on 3G.

The console is a full app — it's designed to work offline for the login shell but heavy pages need data. On 3G, expect 5-10 second load. Once loaded, subsequent navigation is instant (the SW caches the shell).

11.5GST / invoicing issues

My invoice shows IGST instead of CGST+SGST (or vice-versa).

The tax type is decided from state codes: your warehouse state vs the customer's state. Check both. Intra-state → CGST + SGST. Inter-state → IGST. Fix the state code on the record where it's wrong.

IRN / QR code didn't generate on the invoice.

NIC GSP integration isn't configured or has an expired credential. See Part XII § 12.3.

E-way bill number missing on inter-state dispatch.

Same NIC GSP issue, or the dispatch is under the ₹50k threshold where EWB isn't required.

Customer says they never got the invoice email.

Check /notifications/log — filter to that customer + last N days. See if the email was sent, delivered, bounced, or failed. Common cause: their email is wrong on the dealer record.

11.6Stock ledger issues

Stock balance shows a negative number.

Someone dispatched or issued more than was in stock. If the warehouse allows negative (see Part IX § 9.5), this is expected. If not, physical stock and ledger are out of sync — run a cycle count at /inventory/cycle-counts/new and adjust.

Item X is missing from stock reports.

The product's status is DISCONTINUED, or valuation method changed mid-year. Check /products/[id].

Cost of Goods Sold looks wrong on the invoice.

Valuation method (FIFO / LIFO / MOVING_AVERAGE) determines this. FIFO uses oldest cost lot; MOVING_AVERAGE uses running average. If it looks off, check what method the product uses.

I can't edit a posted Stock Entry.

Correct — item quantities and warehouses are immutable once posted. For corrections, raise a reversal + redo entry. Only header metadata (notes, posting date within 14 days) is editable. See Part II § 2.6.

11.7Frequently asked questions

How do I reset a user's password?

HR opens the User row at /hr/employees/[id] and clicks Reset Password. An email with a fresh temporary password goes to the user. For phone-OTP-only workers, no password reset needed — they always use OTP.

Can I delete a lead / dealer / order / invoice permanently?

No. All entities use soft delete (deletedAt) which hides but preserves audit history. Deletion is by policy — records must remain for tax audits (usually 8 years).

How do I fix a typo on an already-posted invoice?

You can't edit a posted invoice. Options: (a) issue a credit note at /finance/credit-notes/new to cancel it, then raise a new correct invoice; (b) for minor cosmetic fixes (spelling), edit metadata fields only (notes, descriptions).

How do I change a dealer's tier?

Edit the dealer at /dealers/[id] → Tier field. Change takes effect on the next quote generated for that dealer.

How do I add Hindi / Punjabi content for a product?

Edit the product at /products/[id] → fill nameHi, taglineHi, summaryHi, namePa, etc. The marketing site + dealer portal auto-pick based on the visitor's locale.

Can I bulk-import 500 dealers from an Excel file?

Yes — see Part XIV. Prepare the CSV to the specified schema, then run scripts/import-dealers.ts on the server. Ask the developer if it's your first time.

How does row-level security work?

Sales role sees leads assigned to their team (via hierarchy). Employees see only their own payslip / attendance. Admins see everything. It's enforced at the database query layer, not the UI — even a URL trick won't reveal restricted data.

Where are backups?

Automated nightly to the VPS backup partition. Off-site sync is manual for now. Recovery procedure in Part XVIII.

Is there a public API for external integrations?

Not a general-purpose one. Specific integration endpoints exist for IndiaMART (webhook), WhatsApp (Cloud API), and warranty registration (public routes). For anything else, ask the developer.

What timezone does the console use?

Asia/Kolkata (IST, UTC+5:30). All timestamps in the database are stored as UTC; the UI renders in IST. Reports respect IST for day boundaries.

Why does an amount show in paise instead of rupees?

Internal storage is in paise (integer) to avoid floating-point errors on money. UI usually converts to rupees for display. If you see 1500000 where you expected 15000, that's paise — multiply by 100 for rupees representation, divide by 100 to convert back.

11.8When to call the developer (Tarun)

Most things you can fix yourself with this manual. Reach out to Tarun Bhardwaj (itarunbhardwaj@gmail.com) when:

• The console is down — https://crm.nicksonpumps.com returns 5xx or won't load at all.
• An error message you can't find in Part XI § 11.1.
• You need a bulk data import that doesn't have a documented importer.
• You need a new integration configured (a new external system).
• Backup restoration is required.
• You suspect a bug — something silently wrong, not a misuse issue.
• You want to change something that's structural — a new role, a new field, a workflow change.

Third-party systems the console talks to. Each has a specific configuration path. Get these right on day-one setup and the whole team runs at automation-speed instead of manual-copy-paste speed.

12.1IndiaMART lead ingest webhook

Auto-ingests every lead delivered by IndiaMART's leads platform into /leads with source = INDIAMART.

1. Log into IndiaMART Seller Panel → Leads Platform → Integrations.
2. Add a new webhook endpoint pointing at https://crm.nicksonpumps.com/api/leads/indiamart.
3. Copy the auth token IndiaMART generates. Set it in Settings → Integrations → IndiaMART Auth Token (or environment variable INDIAMART_WEBHOOK_TOKEN).
4. Test — trigger a fresh IndiaMART lead. It should land in /leads within seconds with the full raw payload preserved.

12.2WhatsApp Cloud API

Powers OTP delivery, invoice PDF share, dispatch alerts, warranty notifications. Uses Meta's WhatsApp Cloud API directly.

1. Register a WhatsApp Business Account at business.facebook.com.
2. Add a phone number and get it verified (the number your customers will see).
3. In the app dashboard → WhatsApp → Getting Started, copy Phone Number ID and permanent Access Token.
4. Set in Settings → Integrations → WhatsApp:
   • WHATSAPP_PHONE_NUMBER_ID — your registered number ID
   • WHATSAPP_ACCESS_TOKEN — permanent token
   • WHATSAPP_APP_SECRET — for webhook verification
   • WHATSAPP_VERIFY_TOKEN — arbitrary string you pick
5. Get message templates approved in the Meta Business Manager. Template names must match the template keys in /notifications.
6. Test — trigger an OTP flow. If it doesn't arrive, check /notifications/log for the delivery status.

12.3GST GSP · IRN + e-way bill

Automates IRN generation on B2B invoices and e-way bill for inter-state dispatches over ₹50k. Uses a GST Suvidha Provider (GSP) — Cleartax, Masters India, or ClearTax are common.

1. Sign up with a GSP. Cleartax is the most SME-friendly; others exist.
2. Get GSP API credentials — client ID, client secret, endpoint URL.
3. Register your GSTIN with the GSP for e-invoicing (IRN) if turnover ≥ ₹5 crore.
4. Set in Settings → Integrations → GST GSP:
   • GSP_ENDPOINT — the GSP's API base URL
   • GSP_CLIENT_ID / GSP_CLIENT_SECRET
   • GST_USERNAME / GST_PASSWORD — your GST portal credentials for e-way bill
   • GSTIN — the GSTIN under which invoices are raised
5. Test — generate a small invoice. IRN + QR should appear. Generate an inter-state dispatch over ₹50k — e-way bill number should populate.

12.4SMTP · outbound email

Powers invoice emails, welcome emails to new users, password resets, notification digests. Uses local Postfix on the VPS by default.

1. SMTP credentials live in /opt/nicksonpumps-crm/.env.local on the VPS.
2. To use an external provider (SendGrid, SES, Mailgun): set SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS.
3. Verify SPF, DKIM, DMARC DNS records are set for nicksonpumps.com — otherwise Gmail marks your emails as spam.
4. Test — trigger a welcome email by onboarding a test employee. Confirm it arrives in inbox (not spam).

12.5PostHog · product analytics

Anonymous product analytics — which pages get used, where users get stuck, session recordings for UX debugging. Not user tracking; product analytics.

1. Sign up at posthog.com (free tier is generous).
2. Get project API key from PostHog settings.
3. Set NEXT_PUBLIC_POSTHOG_KEY and NEXT_PUBLIC_POSTHOG_HOST in .env.local.
4. Redeploy. Events start flowing.

12.6Sentry · error tracking

Captures errors from client and server so Tarun can fix them proactively — without waiting for user reports.

1. Sign up at sentry.io.
2. Create a Next.js project. Get the DSN.
3. Set SENTRY_DSN in .env.local. Set SENTRY_AUTH_TOKEN for release tagging.
4. Redeploy. Any 5xx errors, JS exceptions, or slow requests will appear in Sentry with the exact stack trace.

A few small habits that make everything twice as fast. Once you internalise these, sidebar-clicking feels slow.

Command palette · CtrlK / ⌘K

The fastest way to jump anywhere. Type any of:

• A record identifier — DLR-PB-001, SO-2026-00042, a serial number, a pump SKU
• A page name — "leads", "cash register", "warehouse", "invoices"
• A customer / dealer / vendor name — Balbir, Sharma Steel
• An employee name — Ramesh, Simran

Fuzzy matching. Enter to jump. Escape to close.

Global shortcuts

Form shortcuts

• Tab — next field. ShiftTab — previous.
• Enter in a text field — submits form (except textareas — those need CtrlEnter).
• Esc — cancel / close without saving.
• On line-item tables, Tab from the last cell auto-adds a new row.

QR scanner in the top bar

Camera icon (📷) opens the scanner. Point at any of:

• Pump serial sticker — jumps to serial detail + warranty history
• Package label QR — jumps to dispatch order
• Vendor code QR (some vendor invoices carry one) — jumps to vendor detail
• Dealer QR — jumps to dealer profile

First use asks for camera permission. Grant once, never asks again.

Quick capture bar

The + button top-right (or press n) opens a three-tab picker: New Lead / New Task / New Note. One-tap add without leaving the page you're on.

Power-user tips

• URL as command line. Deep-link to filtered views: /leads?stage=NEW, /leads?assignedToId=<user>, /procurement/grns?status=DRAFT. Bookmark these.
• Middle-click to open in a new tab. Every navigation link supports it. Useful for cross-referencing without losing your place.
• Right-click a record row for a context menu (edit, duplicate, archive).
• The CtrlP (print) layout hides the sidebar and paginates cleanly. Use it to generate PDFs of any list or detail page.

Moving a lot of records at once. Everything list-page has export. Imports are file-based and per-entity. Bulk actions live on the list pages themselves.

Exporting from any list

• Every list page has an Export CSV button in the top-right area (near filters).
• Applied filters carry into the export — export exactly the rows you're seeing.
• For very large exports (over 5000 rows), the export runs as a background job; you'll get a download link in the notification bell when it's ready.
• Reports (AR aging, dashboards) export as CSV or PDF via the same button.

Bulk actions on list pages

Check-boxes on the left of each row allow bulk selection. Once one or more rows selected, a bar appears with actions:

• Assign — reassign selected records to a specific user (Leads, Tasks, Warranty Claims).
• Tag — add or remove tags.
• Change status — bulk stage advance (Leads only).
• Soft delete — hide from all views (requires admin role).
• Export — CSV of the selection.

Importing existing data

Bulk import scripts live in /opt/nicksonpumps-crm/scripts/. Each takes a CSV in a specific schema and upserts. Documented in the script header. Run over SSH:

All import scripts are idempotent — safe to re-run. They upsert by unique key.

Detailed role × action grid. Legend: ● full access · ◐ own records only · — no access.

Every automated message the system can send — when it fires, who gets it, on which channel. Full template bodies live in lib/notifications/email-templates.ts; customise via /settings/integrations.

Sales

Procurement

Manufacturing & Dispatch

HR & Payroll

Finance

Warranty & Service

Every mutation is logged. Two systems: Activity Timeline (record-facing, user-friendly) and Audit Log (system-facing, forensic). Use the first for daily questions; the second for disputes and compliance audits.

Activity Timeline (record-facing)

Every detail page — lead, order, invoice, employee, GRN, etc. — has an Activity section at the bottom that shows:

• Every user-driven action on the record (created, edited, status changed, note added)
• Automated system events (invoice generated, IRN received, notification sent)
• Free-form notes / comments logged by users
• Each entry has timestamp, actor, and (where applicable) a before / after diff

This answers ~90% of "who changed X" questions without needing developer access.

Audit Log (system-facing)

Deeper log at /audit (admin only). Every mutation on every table, immutable, with:

• Actor user ID
• Timestamp (millisecond precision)
• Table + record ID affected
• Operation (INSERT / UPDATE / DELETE)
• Complete before/after JSON snapshot
• IP address + user agent

Filter by user, date range, table, or operation. Export as CSV for audit response.

Common lookups

Data safety — what's backed up, how often, where it lives, and how to restore. Owner should know this at least conceptually; developer executes the recovery.

What's backed up

• PostgreSQL database — the whole thing, including all schemas, tables, indexes, and audit history. Nightly compressed dump.
• Uploaded files — attendance selfies, warranty photos, claim photos, product images, invoice PDFs. Nightly incremental to backup partition.
• Configuration — /opt/nicksonpumps-crm/.env.local (SMTP creds, GSP creds, VAPID keys) — backed up encrypted; separate from the main backup partition.
• Application code — GitHub is the source of truth; not backed up separately.

Backup schedule

• Nightly — full PostgreSQL dump + incremental file backup, both to the VPS's local backup partition /var/backups/nickson/.
• Weekly — off-site sync to a separate storage location (currently manual; Rahul's local drive).
• Retention — 30 days of nightlies on the VPS; 3 months of weekly off-site.

Recovery procedure

If something bad happens — data corruption, accidental bulk delete, ransomware — this is the sequence:

1. Stop the app: pm2 stop nicksonpumps-crm on the VPS.
2. Rename the current database: psql -c "ALTER DATABASE nickson_crm RENAME TO nickson_crm_corrupted"
3. Create a fresh database with the same name.
4. Restore the latest good nightly dump: pg_restore -d nickson_crm /var/backups/nickson/latest.dump
5. Restore uploaded files: rsync -a /var/backups/nickson/uploads/ /opt/nicksonpumps-crm/uploads/
6. Start the app: pm2 start nicksonpumps-crm
7. Verify — log in, check /dashboards/owner, spot-check a few records.
8. Communicate — send a notice to all users about what data is now current (up to which timestamp).

Recovery time objectives

• RPO (Recovery Point Objective) — up to 24 hours of data loss in the worst case. Nightly backups mean transactions during the day since the last backup are lost.
• RTO (Recovery Time Objective) — ~1 hour from disaster to app running again, assuming backups are intact.

A guided tour of every module, framed for adaptation. Not what a module is (that's Part II) — but why it matters to you, what your first task is, how it connects to everything else, and the moment you'll know you've mastered it. Read in order the first time; return to any single lesson later.

19.1How to use this section

Set aside about two hours total. Do the seventeen lessons in order — each 5-10 minutes of reading plus a small hands-on task you can literally do on prod using the seeded data. By the end, you'll have touched every corner of the console at least once and understand where each module fits in the whole.

Every lesson has the same four-block structure:

• Why this matters to you — the business reason to care about this module today, not "one day" or "in theory".
• Your first task — a concrete 5-minute action to try right now. Uses the seeded data so nothing breaks.
• How it connects — the adjacent modules this one feeds into or draws from. Once you see the graph, the whole console clicks.
• Mastery signal — the specific thing you'll be able to do without checking the manual.

19.2The learning path

Suggested reading order. Follow it and each lesson builds on the previous.

19.3Patterns that carry across every module

Five patterns that show up everywhere. Learn them once, apply them everywhere.

• List → Detail → Edit. Every module has a list page, a detail page per record, and an edit form. Sidebar → list → click row → detail. Simple everywhere.
• Sidebar filter by role. What you see depends on your role. If a section is missing, that's by design — you can still ⌘K to jump if allowed.
• Status enums drive workflow. Every record has a status; changing it advances the workflow. Part VII explains every enum in the system.
• Every mutation logs to Activity. Detail page bottom always has an activity timeline — who, when, what changed.
• Numbers stored as paise or integers. Money is paise (₹1 = 100). Percentages are usually 0-100. Time as ISO strings.

19.4Mastery signal — you know the CRM when…

You've absorbed the system when — without checking this manual — you can:

1. Take a phone inquiry from a farmer's cousin and get it into the system with all context captured, in under 2 minutes.
2. Approve a batch of daily-work submissions before your morning tea.
3. Post a market-run cash purchase for bearings on your phone, walking back from Chowk Mehta.
4. Answer any staff question by pulling up their role's view via CtrlK — you know what they see because you've been in their shoes here.
5. Explain to your CA at year-end why the Cash Register books are cleaner than any competitor's.
6. Walk the ISO auditor through the QMS evidence chain from a warranty claim back to the batch and shift.
7. Feel calm on Monday morning because the Owner Brief tells you what to attend to first.

Once you have that pattern, teach it to two other people in the team. That's when you know it's yours.

The last modules that weren't given their own section elsewhere, plus the reference appendices — number-series patterns, glossary, changelog. After this the manual is genuinely complete.

20.1Content Management (CMS)

The console doubles as the CMS for the public marketing site at nicksonpumps.com. Update copy, banners, and industry pages without touching code.

Every content edit auto-triggers ISR revalidation on the marketing site — changes appear live within ~5 seconds. Locale-aware fields (*Hi, *Pa) allow Hindi and Punjabi variants that dealers and end-customers see based on their language switcher choice.

20.2Tasks

A lightweight task system that runs alongside every module. Tasks can be personal (yours only) or assigned to another user. Common uses:

• Follow-up reminders on leads and quotes
• Approval delegation ("Rahul, review this PO before Friday")
• Recurring maintenance reminders
• Personal to-dos that don't fit another module

Fields on the task form:

Title text req

Short description of the task.

Description text · long opt

Full context.

Assignee User picker req

Blank = yourself.

Due date date + time opt

Overdue tasks bubble to the top of the assignee's inbox.

Priority LOW / NORMAL / HIGH / URGENT opt

URGENT surfaces in the notification bell.

Related record picker opt

Optional link to a Lead, Order, Claim, etc. — creates a back-link on that record's activity timeline.

Tasks respect authority scope — via the canAssign() helper, users can only assign to their reports or peers, not to anyone across the org.

20.3Recruitment — full flow

The hiring pipeline. Publish → source candidates → interview rounds → offer → convert to Employee. Everything under /hr/recruitment.

Stages

1. Job opening — /hr/recruitment/openings/new. Title, department, designation, grade, job description, hiring manager, target close date. Publish when ready.
2. Candidate applications — either applied via public careers page or hand-entered by HR. Each has resume upload, source, current CTC, expected CTC.
3. Interview rounds — configurable per opening (screening call, technical, HR round, final). Each round has an interviewer, a scheduled date, notes, and a rating.
4. Offer letter — auto-generated from a template using the candidate's negotiated compensation. Emailed as PDF.
5. Convert to Employee — one click on the accepted candidate creates the EmployeeV2 record with everything pre-filled.

Screens

20.4Salary structures & piece-rate overrides

Two separate payroll systems — structured salary for EmployeeV2 and per-worker piece-rate overrides for TemporaryWorker.

Salary structures (salaried employees)

/hr/salary-structures — templates per grade. A structure defines the earnings + deductions formula:

• Earnings — Basic (usually 40% of gross), HRA (usually 40-50% of basic), Conveyance (fixed), Special allowance (balancer)
• Statutory deductions — PF (12% of Basic, capped at ₹1,800/month), ESI (0.75% of gross for wages ≤ ₹21k/month), Professional Tax (state-specific slab, PB = ₹200/month), TDS (per Income Tax slab)
• Custom deductions — advance recovery, loan EMI, uniform allowance recovery

Attach a structure to an employee via their profile → Compensation Revision. Structures can be revised for salary hikes — the history is preserved.

Piece-rate overrides (temp workers)

/hr/piece-rate-overrides — per-worker rate adjustments to the operation's default rate. Use when a specific worker has consistently higher quality or speed and deserves a bonus rate:

• Pick worker + operation
• Override rate in paise (must be within a reasonable multiplier of default)
• Effective from / to dates
• Approver + reason

20.5Dealer portal — external view

What a dealer sees when they log in with role DEALER_PORTAL. Constrained, self-service, focused on their own account.

Dealer portal login flow:

1. Sales creates the dealer at /dealers/new and marks portal access.
2. Dealer receives a welcome email with a self-registration link.
3. Dealer sets a password, uploads GST + PAN, accepts T&C at /onboard.
4. Sales approves; dealer can now log in at /login.

20.6Approval workflow admin

Not every action goes through immediately. Some require an approval step from an authorised user. This module manages the routing.

Approval kinds

• PO above threshold — set threshold in Settings; higher POs enter PENDING_APPROVAL until approved.
• Expense claims above threshold — usually ₹5k for manager, higher for finance.
• Leave applications — auto-route to reporting manager.
• Vendor payments above threshold — require admin sign-off on the outbound.
• Credit note issuance — accounts-authorised only.
• Salary revision — HR + admin joint approval.

Each approval carries a full audit trail: requester, timestamp, before/after diff, approver's decision, reason note. Everything visible in the record's activity timeline.

20.7Beat planning & lead source configuration

Beat plans

Pre-defined dealer visit routes for the field team. Instead of reps deciding where to go each day, beats structure the week.

• /field/beats — list of all beats
• /field/beats/new — create a beat

Each beat has: name (Amritsar Zone A), day of week, assigned rep, list of dealers to visit that day, expected duration. Reps see today's beat as the top card on /field.

Lead source configuration

/sources — configure the sources that appear in the Lead form's source dropdown. Each source has:

• Code — INDIAMART, WALK_IN, PHONE
• Display name
• Active flag
• Webhook URL (if automated) — for IndiaMART, Facebook Lead Ads, etc.
• Auth token — for verifying webhook payloads
• Default assignee / round-robin group — who owns leads from this source by default
• SLA target — first-response deadline (in hours)

20.8Number series & sequence patterns

Every entity has an auto-generated identifier. Learn these patterns and you can recognise records at a glance.

20.9Glossary of terms

Industry acronyms and Nickson-specific vocabulary used throughout the console. Alphabetical.

AR (aging)

Accounts Receivable. AR aging = how long each customer invoice has been unpaid, bucketed by 0-30 / 31-60 / 61-90 / 90+ days.

BOM

Bill of Materials. The recipe for how to build one output product — components + operations + scrap allowances.

CAPA

Corrective and Preventive Action. Formal quality response to an NCR — root cause + action items + effectiveness verification.

CGST / SGST / IGST

Central / State / Integrated GST. CGST + SGST charged on intra-state supplies (half each); IGST on inter-state (full).

CTQ

Critical-to-Quality. A BOM component flagged as CTQ gets extra QC attention at incoming and in-process stages.

DCR

Daily Call Report. End-of-day summary from field reps.

EWB · e-way bill

Electronic Waybill. Mandatory for inter-state dispatches over ₹50,000 (some states also for intra-state above thresholds). Generated via NIC GSP.

FG

Finished Goods. Warehouse type where completed pumps live before dispatch.

FIFO / LIFO / MOVING_AVERAGE

Inventory valuation methods. See Part VII § 7.2.

GRN

Goods Receipt Note. Formal record that inbound stock has been received.

GSP

GST Suvidha Provider. A licensed intermediary that connects to the government's GST portal for IRN + e-way bill.

GSTIN

GST Identification Number. 15-character format: 2-digit state + 10-char PAN + 1 entity number + 1 check + Z default.

HSN

Harmonised System of Nomenclature. GST commodity classification code. Required on invoices above certain turnovers.

IRN

Invoice Reference Number. Unique NIC-issued code that certifies an invoice under e-invoicing. Mandatory for B2B invoices from businesses with turnover ≥ ₹5 crore.

MOQ

Minimum Order Quantity.

MSME

Micro, Small & Medium Enterprise. Registered via Udyam portal. MSME vendors must be paid within 45 days (MSMED Act 2006 + Section 43B).

NCR

Non-Conformance Report. Quality defect record.

PAN

Permanent Account Number. 10-character tax identity for individuals and businesses.

PF / ESI / TDS

Provident Fund / Employees State Insurance / Tax Deducted at Source. Statutory salary deductions.

POLine / GRNLine / BOMComponent

The individual line items on a Purchase Order, Goods Receipt Note, or Bill of Materials. Each represents one item on the parent document.

Piece-rate

Payment model where a worker is paid per unit completed (not per hour). Common on the shop floor for winding, assembly, testing.

PWA

Progressive Web App. A website that behaves like a native app — installable to home screen, offline-capable, push notifications.

RCM

Reverse Charge Mechanism. Under GST, some transactions require the buyer (not the seller) to pay the tax. Common for purchases from unregistered dealers, scrap traders, some transport.

RFQ

Request For Quotation. A formal price inquiry sent to vendors before raising a PO.

RPO / RTO

Recovery Point Objective / Recovery Time Objective. Backup-and-recovery targets. See Part XVIII.

Section 269ST

Income Tax Act section that caps cash transactions at ₹2 lakh. Cross it and Section 271DA imposes a 100% penalty.

Section 43B

Income Tax Act section that disallows expenses (like MSME payments beyond 45 days) as deductions if unpaid.

SLE

Stock Ledger Entry. The immutable per-item cost queue that drives FIFO / LIFO valuation.

SO / PO

Sales Order (customer) / Purchase Order (vendor). Same shape, opposite direction.

SKU

Stock Keeping Unit. Unique identifier for a product variant.

SWG

Standard Wire Gauge. Copper-wire thickness system used in stator winding. Lower SWG number = thicker wire.

TDS

Tax Deducted at Source. Buyer withholds a percentage of vendor payment and remits to government.

UAN

Universal Account Number. Employee's PF portable identity across employers.

Udyam

The current MSME registration portal (replaced the older Udyog Aadhaar).

UoM

Unit of Measure. Nos / Kg / Mtr / Ltr / EACH.

UTM

URL parameters (utm_campaign, utm_medium, utm_source, utm_content) used to attribute web traffic to specific marketing campaigns.

V3 / V4 / V6

Nickson's submersible pump form factors — V3 (3-inch dia), V4 (4-inch), V6 (6-inch). Larger = higher discharge, deeper wells.

WIP

Work-in-Progress. Warehouse type where partially-built products live between raw material issue and finished output.

WO / Work Order

A production batch instruction. Turns a BOM into actual output.

20.10Version history · how the CRM got here

The console has evolved through several distinct phases. This is what shipped in each — useful when someone asks "when did we get X".

• Core Leads, Dealers, Products, Commerce (quotes + orders), Procurement, Manufacturing, Inventory, HR + Payroll
• PWA install, mobile shell, ⌘K command palette, QR resolver
• Quick-capture bar, Owner Daily Brief

• Activity thread on every record
• Approval inbox at /workflows-admin/approvals
• Dealer portal (external self-service)
• Web push notifications (VAPID)
• Bulk lead actions + CSV export
• Offline queue (IndexedDB)
• Dark mode

• Pluggable adapter framework — WhatsApp (Gupshup / Meta), GST (Cleartax), transcription (Whisper / Sarvam), weather (IMD)
• Mock adapter as default; env flag switches to real
• Schema audit: every transactional model has dealerId — dealer portal live-data-ready

• Voice STT wired into captures (Whisper / Sarvam)
• IRN + e-way bill via GspAdapter
• Dealer portal warranty / order / dispatch forms
• AR aging report
• Owner Daily Brief + demand-forecast dashboard widget
• WhatsApp inbound webhook

• WhatsApp direct to Meta Cloud API (no GSP dependency)
• e-Way Bill direct to NIC
• IndicWhisper + PaddleOCR Python sidecars for local transcription and photo-OCR
• Open-Meteo weather (no key)
• IndiaMART + Justdial direct integrations
• Photo captures auto-OCR; voice auto-transcribed

• Linear-grade OKLCH design tokens with dark-mode inverted brand
• 5 UI primitives (PageHeader, EmptyState, Pill, KpiTile, DataTable)
• Linear-tight AppShell
• 127-file retroactive polish across the whole console
• 68/68 pages green post-deploy

• Cash-purchase GRN flow — ad-hoc vendor mode, no-PO receipts
• Vendor–Part directory (derived from GRN history)
• Stock Entry metadata edit (safe, header-only)
• Owner dashboard (already shipped in Phase 4)
• Cash Register with 11 legal exemption categories, Section 269ST guardrail, vendor threshold advisory

• Test users for every role + demo workflow seed + master data seed + day-one data seed
• Employee model unified under one AppShell (retired the separate /e mobile shell)
• Nickson CRM operations manual v1.0 → v1.6 — this document
• Real vendor / product / operation seed data for immediate usability

Every phase's commits, decisions, and gotchas are logged in the git history. When you need to trace "why is X the way it is", git blame + the commit message is the source of truth.