# Sales Intelligence Dashboard

A PHP-based analytics dashboard that integrates with GoHighLevel (GHL), Facebook Ads, Twilio, and Stax to provide comprehensive sales funnel analytics and performance metrics.

## What This Dashboard Does

This dashboard provides a complete view of your sales pipeline by pulling data from multiple sources and presenting key metrics about leads, calls, demos, and closed deals.

## Key Features

### 1. Sales Funnel Tracking
- Tracks leads from initial contact through to closed deals
- Shows conversion rates between each stage (Lead → Call 1 → Demo → Close)
- Identifies drop-off points in the sales process
- Displays cost per acquisition at each stage

### 2. Two Reporting Modes

**Cohort Mode** (default)
- Groups contacts by their lead creation date
- Tracks progression regardless of when it happens
- Rates always compare the same population
- Best for: Performance reviews and accurate conversion analysis

**Activity Mode**
- Counts stage events that occurred within selected date range
- Shows what happened during a specific time period
- Best for: Operational snapshots and weekly reporting

### 3. Agent Performance
- Individual performance metrics for each sales agent
- Shows leads, calls scheduled, demos set, and closed deals per agent
- Calculates conversion rates and estimated costs per agent
- Compares performance across the team

### 4. Data Quality Monitoring
- Identifies missing fields in your CRM
- Detects out-of-order stage dates
- Flags deals closed without revenue data
- Shows data cleanliness percentage

### 5. Integration Data

**GoHighLevel (GHL)**
- Fetches all contacts with custom fields
- Maps custom field IDs to readable field names
- Handles pagination for large contact lists

**Facebook Ads (via GHL)**
- Pulls ad spend, impressions, clicks, and reach
- Calculates CPM and CPC

**Twilio**
- Fetches call logs for the selected period
- Shows total calls, answered calls, and average duration

### 6. Period Comparison
- Compares current period against previous period of same length
- Shows delta (↑/↓ percentage) on all key metrics
- Tracks improvement or decline over time

## Metrics Tracked

| Metric | Description |
|--------|-------------|
| Paid Leads | Contacts with date_lead_created in period |
| Call 1 Scheduled | Calls scheduled from leads |
| Call 1 Given | Calls that actually happened |
| Demo Scheduled | Demos scheduled after call |
| Demo Confirmed | Demos confirmed by client |
| Demo Given | Demos that took place |
| Closed Deals | Deals that closed |
| Upfront Cash | Total upfront revenue collected |
| ROAS | Return on ad spend (revenue ÷ spend) |
| CPL | Cost per lead |
| CPA | Cost per acquisition at each stage |

## Data Sources

| Integration | Purpose | Authentication |
|-------------|---------|----------------|
| GoHighLevel | Contact data, custom fields, stage dates | API Key |
| Facebook Ads | Ad spend, impressions, clicks (via GHL) | GHL integration |
| Twilio | Call logs, duration, answer rates | Account SID + Token |
| Stax | Payment/transaction data (configurable) | API Key |

## Custom Fields Required in GHL

The dashboard looks for these custom fields on contacts:

**Date fields:**
- `date_lead_created`
- `date_review_tag_added`
- `date_call_1_was_scheduled`
- `date_call_1_no_showed`
- `date_call_1_was_given`
- `date_demo_was_scheduled`
- `date_demo_was_confirmed`
- `date_client_completed_full_predemo_orientation`
- `date_demo_no_showed`
- `date_demo_was_given`
- `date_customer_closed`
- `date_post_demo_follow_up_started`
- `date_added__around_the_boat`

**Money fields:**
- `client_buildout_fee_paid_reporting`
- `client_retainer_fee_reporting`
- `upfront_cash_collected_reporting`

## Configuration

Edit the constants at the top of the file:

```php
define('GHL_API_KEY',        'your-ghl-api-key');
define('GHL_LOCATION_ID',    'your-location-id');
define('TWILIO_ACCOUNT_SID', 'your-twilio-sid');
define('TWILIO_AUTH_TOKEN',  'your-twilio-token');
define('STAX_API_KEY',       'your-stax-api-key');
```

## Usage

1. Configure API credentials in the file
2. Deploy to a PHP-enabled web server
3. Access the dashboard via browser
4. Use filters to select date range, agent, and reporting mode

## Filter Options

- **Period Presets**: Last 30 days, This month, Last month, Last 7 days, Today
- **Custom Date Range**: Select any start and end date
- **Agent Filter**: View data for specific agent or all agents
- **Reporting Mode**: Cohort or Activity

## Demo Mode

If API credentials are not configured, the dashboard automatically uses demo data to show how it works.

## Technical Notes

- The dashboard paginates through all GHL contacts using cursor-based pagination
- Agent ad spend is attributed proportionally by lead share (not evenly split)
- "Inferred" stage counts occur when a downstream field exists without the parent field
- Twilio data is account-wide and not stage-matched to specific contacts