Sales Module Technical Specifications

Overview

Complete sales pipeline management system with lead capture, opportunity tracking, and customer conversion workflows.

Data Models

1. Lead Entity

{
  "id": "uuid",
  "name": "string",
  "owner_id": "uuid", // FK to User
  "source": "enum[website, google_ads, facebook, privy, typeform, bulk_upload, manual]",
  "created_at": "timestamp",
  "prospective_type": "enum[individual, sme, corporate]",
  "priority": "enum[hot, warm, cold]",
  "contact_info": {
    "email": "string",
    "phone": "string",
    "whatsapp": "string"
  },
  "tags": "array[string]",
  "notes": "text",
  "status": "enum[new, contacted, qualified, disqualified]",
  "updated_at": "timestamp"
}

2. Opportunity Entity

{
  "id": "uuid",
  "lead_id": "uuid", // FK to Lead
  "deal_name": "string",
  "expected_close_date": "date",
  "deal_stage": "enum[discovery, proposal_sent, negotiation, won, lost]",
  "value_estimate": "decimal",
  "assigned_to": "uuid", // FK to User
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

3. Customer Entity

{
  "id": "uuid",
  "opportunity_id": "uuid", // FK to Opportunity
  "lead_id": "uuid", // FK to Lead
  "customer_success_manager": "uuid", // FK to User
  "purchase_history": "array[object]",
  "onboarding_status": "enum[pending, in_progress, completed]",
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

4. Activity Entity

{
  "id": "uuid",
  "entity_type": "enum[lead, opportunity, customer]",
  "entity_id": "uuid",
  "activity_type": "enum[call, email, whatsapp, meeting, proposal, quotation]",
  "description": "text",
  "completed": "boolean",
  "scheduled_at": "timestamp",
  "completed_at": "timestamp",
  "created_by": "uuid", // FK to User
  "metadata": "json" // Additional data like call duration, email subject, etc.
}

5. Sales Order Entity

{
  "id": "uuid",
  "opportunity_id": "uuid", // FK to Opportunity
  "order_number": "string",
  "total_value": "decimal",
  "status": "enum[pending, confirmed, delivered, cancelled]",
  "invoice_generated": "boolean",
  "payment_status": "enum[pending, paid, failed]",
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

API Endpoints

Lead Management

POST   /api/leads                    // Create new lead
GET    /api/leads                    // List leads with filters
GET    /api/leads/{id}               // Get lead details
PUT    /api/leads/{id}               // Update lead
DELETE /api/leads/{id}               // Delete lead
POST   /api/leads/{id}/convert       // Convert to opportunity

Opportunity Management

POST   /api/opportunities            // Create opportunity
GET    /api/opportunities            // List opportunities
GET    /api/opportunities/{id}       // Get opportunity details
PUT    /api/opportunities/{id}       // Update opportunity
POST   /api/opportunities/{id}/close // Close as won/lost

Activity Management

POST   /api/activities               // Log activity
GET    /api/activities               // List activities
GET    /api/{entity_type}/{id}/activities // Get entity activities
PUT    /api/activities/{id}          // Update activity

Communication Actions

POST   /api/leads/{id}/call          // Initiate call
POST   /api/leads/{id}/email         // Send email
POST   /api/leads/{id}/whatsapp      // Send WhatsApp message
POST   /api/leads/{id}/schedule      // Schedule meeting

Business Logic Flows

1. Lead Creation Workflow

Input Sources → Lead Validation → Lead Creation → Owner Assignment → Notification

Implementation Steps:

1. Validate required fields
2. Determine lead source and apply source-specific logic
3. Auto-assign owner based on rules (round-robin, territory, etc.)
4. Send notification to assigned owner
5. Log creation activity

2. Lead Interaction Workflow

Lead View → Action Selection → Communication → Activity Log → Follow-up Automation

Implementation Steps:

1. Display lead timeline and summary
2. Provide quick action buttons (call, email, WhatsApp, schedule)
3. Execute selected action (integrate with VOIP, email service, WhatsApp API)
4. Log activity with timestamp and details
5. Trigger automated follow-up if configured

3. Lead to Opportunity Conversion

Lead Qualification → Conversion Trigger → Data Mapping → Opportunity Creation → Pipeline Entry

Implementation Steps:

1. Validate lead qualification criteria
2. Create opportunity record
3. Map lead data to opportunity fields
4. Set initial deal stage
5. Maintain relationship link between lead and opportunity

4. Proposal/Quotation Process

Opportunity → Document Generation → Client Review → Acceptance/Rejection → Next Stage

Implementation Steps:

1. Generate proposal/quotation from templates
2. Send via email/WhatsApp
3. Track document status (sent, viewed, accepted, rejected)
4. Update opportunity stage based on response
5. Log all interactions

5. Customer Conversion

Opportunity Won → Customer Record Creation → Onboarding Initiation → CSM Assignment

Implementation Steps:

1. Create customer profile
2. Copy relevant data from lead/opportunity
3. Generate welcome email
4. Assign Customer Success Manager
5. Set up onboarding workflow

Integration Points

External Services

• VOIP Integration: For call functionality
• Email Service: SMTP/API for email communication
• WhatsApp Business API: For messaging
• Payment Gateways: Razorpay, Stripe for payment processing
• Calendar Integration: Google Calendar, Outlook
• Lead Capture Tools: Privy, Typeform, etc.

Database Relationships

Lead (1) → (1) Opportunity → (1) Customer
Lead (1) → (n) Activities
Opportunity (1) → (n) Activities
Customer (1) → (n) Activities
Opportunity (1) → (1) Sales Order

Automation Rules

Trigger-Based Actions

1. Lead Creation: Auto-assign owner, send notification
2. Activity Completion: Send thank-you message, log interaction
3. Opportunity Won: Create customer, initiate onboarding
4. Scheduled Follow-ups: Send reminders, create tasks

Periodic Jobs

1. Lead Scoring: Update lead priorities based on engagement
2. Opportunity Aging: Alert on stale opportunities
3. Customer Check-ins: Automated periodic outreach
4. Contract Renewals: Renewal reminders and alerts

UI/UX Components

Lead Management Interface

• Lead list with filters and search
• Lead detail view with timeline
• Quick action buttons
• Bulk operations (import, export, assign)

Opportunity Pipeline

• Kanban board view by stages
• Deal cards with key metrics
• Drag-and-drop stage updates
• Pipeline analytics

Communication Hub

• Integrated email composer
• WhatsApp message templates
• Call logging interface
• Meeting scheduler

Security & Permissions

Role-Based Access

• Admin: Full access to all features
• Sales Manager: Team visibility and reporting
• Sales Rep: Own leads/opportunities only
• Customer Success: Customer records and activities

Data Protection

• Encrypt sensitive contact information
• Audit trail for all data changes
• GDPR compliance for data handling
• Regular backup and recovery procedures

Performance Considerations

Database Optimization

• Index on frequently queried fields (owner_id, status, created_at)
• Partition activity tables by date
• Implement soft deletes for data retention
• Use database views for complex reporting queries

Caching Strategy

• Cache frequently accessed lead/opportunity data
• Cache user permissions and role assignments
• Implement Redis for session management
• Use CDN for static assets and documents

Monitoring & Analytics

Key Metrics

• Lead conversion rates by source
• Average deal size and close time
• Sales rep performance metrics
• Pipeline health indicators

Reporting Requirements

• Lead source effectiveness
• Sales funnel conversion rates
• Revenue forecasting
• Activity and engagement reports