Skip to content

CRM Master Use Cases (CRM)

Module Purpose: Native Pebble CRM system for company master data management, featuring flexible multi-location tracking, social media integration, and AI-powered insights tailored for chemical distribution operations.

Use Case Quick Reference

ID Title Priority
US-CRM-001 Create Company Record P1
US-CRM-002 Manage Company Information Tabs P1
US-CRM-003 Add Social Media Channels P1
US-CRM-004 Track Multi-Location Customers P1
US-CRM-005 Manage Vendor Empanelment (FEP) P1
US-CRM-015 AI Assistant for Customer Queries P0
US-CRM-017 Activity Timeline View P1
US-CRM-021 Document Repository with OCR P0
US-CRM-022 Duplicate Detection P0
US-CRM-030 GST/PAN Validation P1
US-CRM-031 Credit Limit Rules P1
~~US-CRM-036~~ ~~Legacy Field Discovery & Mapping~~ ~~Out of Scope~~
US-CRM-060 Activity Next-Step Logic P2
US-CRM-061 End-Client (B2B2C) Mapping P2
US-CRM-062 Visual Stage Indicator P2

Priority Legend: P0 = High Priority (Differentiator), P1 = MVP Core, P2 = Phase 2, P3 = Future Enhancement

US-CRM-001: Create Company Record

Purpose: Enable sales reps to create new company records with basic information, cascading address dropdowns, and multi-value communication fields to start tracking potential customers.

Property Value
Actor Sales Rep, Sales Manager
Trigger User clicks "Add Customer" button
Preconditions - User authenticated with CRM access
- Country/State/City master data populated
Priority P1

Main Success Scenario (Creation & Ownership)

  1. Form Initiation
  2. User clicks "Add Customer"

  3. System auto-assigns the user as the Unallocated Owner (Record Creator).

  4. Corporate Hierarchy & Duplication

  5. User enters CIN Number.
  6. System performs exact match check. If exists, blocks creation: "❌ Master record already exists for CIN [Number]".
  7. User selects Tier: Group Company, Parent Company, or Master/Unit Company.

  8. If "Unit", user tags the Parent record.

  9. Cascading Address & Pincode Selection

  10. User selects Country (Dropdown).
  11. System filters State list.
  12. User selects State. System auto-assigns Zone (North/South/East/West) based on state.
  13. User selects City → District.
  14. User enters Pincode. System triggers online verification API.

  15. Verification: System captures a screenshot of the pincode validation for the audit trail.

  16. Business Categorization (Manufacturer Tagging)

  17. User selects Business Type (e.g., Manufacturer, Wholesaler).
  18. User specifies if this type applies to "This Unit" or "All Units".

  19. If "Manufacturer", system forces tagging of specific Products and Industries.

  20. Contact & Email Logic

  21. User enters Corporate Email.
  22. User adds a Contact Master (sub-form).

  23. Alert: If Contact Email matches Corporate Email, system displays: "⚠️ Contact email is identical to corporate email."

  24. Ownership Allocation

  25. User (Admin/Manager) assigns an Allocated Owner (Account Manager responsible for transactions).

  26. Record Finalization

  27. User clicks "Save". System generates unique ID and flags as "Active".
  28. Lead Triage: User assigns a Lead Temperature (Hot | Warm | Cold).
  29. Activity Logging: Every call/email session can be tagged with: Called, Dropped, Responded, Invalid Phone/Email.
Detailed Acceptance Criteria - [ ] User can access "Add Customer" button from main interface - [ ] Form displays Company Name, Address (Country/State/City cascading dropdowns), Mobile (4 fields), Email (3 fields), Website, SAP Code - [ ] Country dropdown auto-populates State dropdown; State auto-populates City dropdown - [ ] Form validates required fields (Company Name, Country, at least 1 mobile) - [ ] On save, system generates unique Customer ID - [ ] System displays success message and redirects to view mode of created company

US-CRM-002: Manage Company Information Tabs

Purpose: Provide an organized 8-tab interface to manage complex customer data, ensuring specialized focus on commercial compliance and engagement history.

Acceptance Criteria & Logic - [ ] Interface displays 8 tabs: **Main Information**, **Branches/Units**, **Contacts**, **Content Broadcasted**, **Products Purchased**, **Present Suppliers**, **Agents**, and **Employee Handling**. - [ ] Clicking a tab switches the view without page reload. - [ ] Active tab is visually highlighted. - [ ] Unsaved changes warning appears if user tries to switch tabs with pending edits. - [ ] **Website Logic**: Allow multiple URL formats (website, LinkedIn, etc.) without fixed label constraints. - [ ] **Privacy**: "Personal Information" tab is deprecated for business entities.

US-CRM-003: Add Social Media Channels

Purpose: Track modern communication identifiers (WhatsApp, LinkedIn, Skype) directly within the CRM master to ensure seamless engagement across channels.

Acceptance Criteria - [ ] Main tab displays fields for WhatsApp (3 numbers), Skype ID, Telegram, Facebook, LinkedIn. - [ ] WhatsApp fields validate phone number format. - [ ] LinkedIn/Facebook fields accept URLs or profile handles. - [ ] All social media fields are optional.

US-CRM-004: Track Multi-Location Customers

Purpose: Manage complex corporate hierarchies where a single legal entity has multiple delivery units (Plants/Warehouses/Branches) as sub-masters.

Acceptance Criteria & Inheritance Logic - [ ] "GST/Address" tab allows adding multiple "Units". - [ ] Units inherit **Group Price** logic from the parent record. - [ ] Each unit must have an address-specific GST mapping. - [ ] List view shows hierarchy: Company → Location → Department → Contact.

US-CRM-005: Manage Vendor Empanelment (FEP)

Purpose: Enforce a "Factory Empanelment Process" (FEP) to ensure compliance and technical approval before commercial transactions are permitted.

Acceptance Criteria - [ ] Location form displays FEP Status dropdown (Pending/Approved/Rejected). - [ ] FEP Status can only move: Pending → Approved or Pending → Rejected (no reverse without Admin). - [ ] System prevents order creation if FEP Status = Pending for a selected unit. - [ ] Transition to "Approved" requires Drug License No, GST, and at least 1 uploaded document.

US-CRM-015: AI Assistant Queries

Purpose: Provide natural language query interface for CRM data, enabling users to ask questions like "What was the last price we quoted?" and get instant synthesis of history and precedent.

Alpha Pebble Playbook: Enterprise Context Layer & Precedent Engineering.

Main Success Scenario (Contextual Retrieval & Synthesis)

  1. Unified Query Input
  2. User clicks the floating AI Assistant button.

  3. User types: "What was the last price we quoted for Zinc Oxide to this client?"

  4. Semantic Search & Intelligence

  5. System queries the Unified Semantic Index.
  6. Finds the historical email thread (Email Stream), the linked Quotation PDF, and the CRM Lead score.

  7. AI extracts the "Decision Trace": "Note: We offered a 5% discount last time due to bulk volume."

  8. Consolidated Response

  9. System displays the price, the date, and a deep link to the email.

  10. Displays a "Playbook Alert": "💡 Precedent found: Consistent 5% discount for bulk Resin orders."

  11. Actionable Suggestions

  12. AI suggests: "Ask if they want the same bulk discount applied to this new enquiry?"
Detailed Acceptance Criteria - [ ] AI Assistant input box available on every page. - [ ] AI Assistant parses query and returns results in table or card format. - [ ] AI can suggest follow-up questions based on the retrieved context. - [ ] System logs all AI queries for audit and continuous model improvement.

US-CRM-016: Advanced Search & Filters

Purpose: Enable high-speed retrieval of specific corporate and contact records using multi-factor filtering, essential for Managing Directors and HODs to audit their business territory.

Acceptance Criteria & Search Logic - [ ] Support universal search across: **Customer Name**, **GST Number**, **CIN**, **Mobile**, **Email**. - [ ] Filter by **Hierarchy Level** (Group vs. Parent vs. Unit). - [ ] Filter by **Entity Type** (Prospect vs. Customer). - [ ] Filter by **Ownership** (Allocated Owner vs. Unallocated). - [ ] High-frequency filters: **State**, **Zone**, **Industry**, **Zoning Error** (Flagged if Pincode doesn't match State). - [ ] Search speed must be < 500ms for datasets up to 100k records.

US-CRM-017: Activity Timeline View (Unified Stream)

Purpose: Provide a single, chronological "Source of Truth" for every interaction with a customer, treating all data (Emails, Kanban moves, ERP syncs) as an immutable activity stream.

Alpha Pebble Playbook: Activity-Stream Engineering & Precedent Engineering.

Implementation Detail - [ ] **Consolidated Feed**: Fetches real-time events from the `ActivityStream`. - [ ] **Precedent Layer**: Surfaces **Decision Traces** extracted by AI (e.g., "Supplier B chosen because of 24h lead time"). - [ ] **Intelligence Filtering**: Allows filtering by **Significance** (e.g., "Show only critical decision points").

US-CRM-021: Document Repository with OCR

Purpose: Centralize all compliance documents (ISO, MSDS, Drug License) with automatic data extraction to eliminate manual data entry errors.

Acceptance Criteria - [ ] "Documents" tab displays a table: Filename, Type, Upload Date, and Extracted Data. - [ ] Drag-and-drop support for PDF/JPG. - [ ] System runs OCR to extract Drug License No, GST No, PAN, and Expiry Dates. - [ ] User can review and approve extracted data before it updates the Master Record.

US-CRM-022: Duplicate Detection

Purpose: Prevent fragmentation of customer data by using fuzzy matching on names and exact matching on tax identifiers (GST/PAN).

Acceptance Criteria - [ ] **Fuzzy Match**: Triggers on name entry (>80% similarity warning). - [ ] **Exact Match**: Blocks creation if GST number already exists in the system. - [ ] **Audit Trail**: Logs all duplicate warnings and user overrides for manager review.

US-CRM-030: GST/PAN Validation

Purpose: Ensure data integrity by validating tax identifiers against government records via API.

Acceptance Criteria - [ ] Calls GSTIN Verification API to validate authenticity and fetch legal name. - [ ] Green checkmark displayed on "Verified" result; blocks save on "Invalid". - [ ] **Fallback**: If API is down, performs format-only regex validation with a "Verification Pending" flag.

US-CRM-031: Credit Limit Rules

Purpose: Enforce financial discipline by linking CRM status to credit utilization and payment history.

Acceptance Criteria - [ ] Calculates Utilization % = (Outstanding / Credit Limit). - [ ] Blocks "Closed Won" moves or order generation if limit exceeded >100%. - [ ] High-utilization alerts (>90%) sent to Credit Manager and Account Owner.

~~US-CRM-036: Legacy Field Discovery & Mapping~~

STATUS: REMOVED FROM SCOPE

US-CRM-060: Activity Next-Step Logic

  • Purpose: Enforce a "Next Step" culture by making it mandatory to schedule a future action every time a current activity is logged.
  • Source Idea: Industrial Workflow Reference
  • Acceptance Criteria:
    • Activity log form includes mandatory "Next Action Type" and "Next Action Date".
    • On save, system auto-generates a placeholder card in the "Follow-up" pipeline for that date.
    • Prevents saving an activity with "No further action" without manager override.

US-CRM-061: End-Client (B2B2C) Mapping

  • Purpose: Provide visibility into the "End Client" in distribution scenarios where the direct customer is a dealer or agent.
  • Source Idea: Industrial Enquiry Reference
  • Acceptance Criteria:
    • Enquiry/Lead form includes an optional "End Client" lookup field.
    • If End Client is already in CRM Master, show their historical preferences/makes.
    • Reports can be filtered by "End Client" to see project-level aggregate demand.

US-CRM-062: Visual Stage Indicator

  • Purpose: Provide instant visual orientation of a lead's journey status using a prominent horizontal progress bar.
  • Source Idea: Industrial Stage Interface Reference
  • Acceptance Criteria:
    • Horizontal progress bar displays stages: Awareness → First Meeting → Demo → Proposal → Review → PO.
    • Current stage is highlighted in a distinct color (e.g., Primary Blue).
    • Bar is click-interactive (for users with "Stage Override" permissions).

Functional Bridge: Kanban Integration

To maintain industrial control while using standard Kanban, the Pebble CRM acts as the Logic Master for all board movements.

Feature Logic Handler Implementation
State Validation Pebble CRM Service Moves to "Qualified" are blocked by CRM if CIN/PAN/GST is missing.
Extended Data Pebble CRM Sidecar Clicking a card opens the 8-tab Industrial View in the Pebble UI.
Identity Triage Pebble CRM Master CRM performs real-time GST/MCA verification when ingestion occurs.
Ownership Pebble CRM Service Map Plane Card Assignees to CRM Allocated Owners.

[!NOTE] API Flow: The CRM UI does not call the Kanban API. The Pebble Backend brokers all transactions. When you move a card in Plane, the Backend receives a webhook, validates the CRM rules, and then updates the CRM state.

Cross-Module Dependencies

Integrates With

Provides Data To

  • Sales Follow-up module (customer assignments)
  • Quotation & Costing module (customer-specific pricing)
  • Operations & Logistics (delivery locations from CRM multi-location tracking)

Technical Architecture

Backend: Django 4.2+ with PostgreSQL 14+
Frontend: React/Next.js with Server-Side Rendering
AI Engine: Ollama (local) or OpenAI API
Knowledge Index: Centralized Semantic Vector Store

Key Design Patterns: - Enterprise Context Layer: Universal Context Container for company data - Precedent Engineering: AI-extracted decision traces for customer negotiations - Activity-Stream Engineering: Immutable event log of all customer interactions

← Back to Use Cases