# Automated Lead Follow-Up System (TRACTOR)

## Overview
The Automated Follow-Up System (nicknamed "TRACTOR") automatically schedules follow-ups after interactions with leads (emails, calls). Based on research showing that sales are usually made after the 8th follow-up, this system ensures continuous engagement until leads are closed, dead, or converted.

## Features

### Automatic Follow-Up Scheduling
- **Triggers:** Automatically schedules follow-ups when:
  - An email is sent to a lead
  - A call is logged for a lead
- **Interval Calculation:** Follow-up intervals are calculated based on:
  - Lead rating (HOT: 1 day, WARM: 2 days, COLD: 3 days)
  - Activity type (EMAIL: +1 day, CALL: -1 day)
- **Calendar Integration:** Creates calendar events for scheduled follow-ups
- **Activity Tracking:** Logs system activities for each scheduled follow-up
- **IMPORTANT:** Automatic email sending is DISABLED by default. The system only schedules follow-ups and creates calendar reminders. Users must send emails manually.

### Follow-Up Management
- **Per-Lead Toggle:** Enable/disable follow-up system for individual leads
- **Follow-Up Counter:** Tracks number of follow-ups completed
- **Status Display:** Shows last follow-up date and next scheduled follow-up
- **Overdue Detection:** Highlights overdue follow-ups in red

### Automatic Stopping
The system automatically stops scheduling follow-ups when:
- Lead status is `CLOSED_LOOP`, `DEAD`, `CONVERTED`, or `NO_CONTACT`
- Follow-up is manually disabled for the lead

## Database Schema

### New Columns in `leads` Table
- `followup_enabled` (BOOLEAN, DEFAULT TRUE) - Enable/disable follow-up for this lead
- `followup_count` (INT, DEFAULT 0) - Number of follow-ups completed
- `last_followup_at` (DATETIME, NULL) - Last follow-up activity timestamp
- `next_followup_at` (DATETIME, NULL) - Next scheduled follow-up date/time
- `followup_interval_days` (INT, DEFAULT 1) - Days between follow-ups

### New Columns in `activities` Table
- `followup_scheduled` (BOOLEAN, DEFAULT FALSE) - Whether a follow-up was scheduled from this activity
- `followup_event_id` (CHAR(36), NULL) - Calendar event ID for scheduled follow-up

## Files Created/Modified

### New Files
1. **`php/includes/classes/FollowUpService.php`**
   - Core service class for follow-up management
   - Methods: `scheduleFollowUp()`, `setFollowUpEnabled()`, `getOverdueFollowUps()`, `processOverdueFollowUps()`

2. **`api/followup-toggle.php`**
   - API endpoint to enable/disable follow-up for a lead
   - POST method with CSRF protection

3. **`scripts/followup-processor.php`**
   - Cron job to process overdue follow-ups
   - Sends reminders for overdue follow-ups
   - Run daily: `0 9 * * * /usr/bin/php /var/www/html/scripts/followup-processor.php`

4. **`php/database/add_followup_tracking.sql`**
   - Database migration script
   - Adds follow-up tracking columns to `leads` and `activities` tables

### Modified Files
1. **`php/api/activities.php`**
   - Integrated FollowUpService to schedule follow-ups after EMAIL and CALL activities

2. **`php/includes/classes/EmailService.php`**
   - Integrated FollowUpService to schedule follow-ups after emails are sent

3. **`lead-detail.php`**
   - Added follow-up system UI section
   - Shows follow-up status, count, last/next follow-up dates
   - Toggle to enable/disable follow-up per lead
   - JavaScript function `toggleFollowUp()` to handle toggle

## Usage

### Enabling/Disabling Follow-Up
1. Navigate to a lead detail page
2. In the "Lead Information" card, find the "Automated Follow-Up System (TRACTOR)" section
3. Toggle the checkbox to enable/disable follow-up for that lead

### Viewing Follow-Up Status
The follow-up section displays:
- **Follow-ups Completed:** Total number of follow-ups
- **Last Follow-up:** Date/time of last follow-up activity
- **Next Follow-up:** Date/time of next scheduled follow-up (highlighted in red if overdue)

### Calendar Events
Follow-ups are automatically added to the calendar as events:
- **Title:** "Follow-up #X: [Lead Name] ([Company])"
- **Time:** 9:00 AM on the scheduled date
- **Duration:** 30 minutes
- **Priority:** HIGH
- **Reminder:** 15 minutes before
- **Color:** Red (#EA001E)

## Cron Job Setup

Add to crontab to process overdue follow-ups daily:
```bash
0 9 * * * /usr/bin/php /var/www/html/scripts/followup-processor.php >> /var/log/followup-processor.log 2>&1
```

## Integration Points

### Activity Creation
When an EMAIL or CALL activity is created:
1. Activity is logged in `activities` table
2. FollowUpService checks if follow-up is enabled for the lead
3. If enabled, calculates next follow-up date based on rating and activity type
4. Creates calendar event for follow-up
5. Updates lead with follow-up information
6. Logs system activity

### Email Sending
When an email is sent via EmailService:
1. Email is sent and logged
2. Activity is created for the email
3. FollowUpService schedules follow-up (same as activity creation flow)

## Future Enhancements
- Custom follow-up intervals per lead
- Email reminders for upcoming follow-ups
- Follow-up templates/suggestions
- Analytics dashboard for follow-up effectiveness
- Integration with email templates for follow-up emails

## Status
✅ **COMPLETE** - System is fully implemented and deployed