# Intel Tagging System

> Tag and categorize intel for quick filtering and smart lists

**Created:** Jan 20, 2026
**Status:** Plan Ready
**Effort:** 3-4 hours
**Ongoing Cost:** $0

---

## Problem

Intel is unstructured text. Can't quickly filter:
- "Show all leads who mentioned budget concerns"
- "Find leads interested in residential work"
- "List leads with hiring needs"

---

## Solution

Tag system for categorizing intel with auto-tagging from AI extraction.

### Tag Categories

| Category | Example Tags |
|----------|--------------|
| **Objections** | `budget`, `timing`, `competitor`, `not-interested`, `need-approval` |
| **Interest** | `residential`, `commercial`, `government`, `high-rise` |
| **Status** | `hiring`, `expanding`, `downsizing`, `new-business` |
| **Sentiment** | `positive`, `negative`, `neutral`, `frustrated` |
| **Priority** | `hot-lead`, `decision-maker`, `referral-source` |

### Auto-Tagging

AI extracts tags automatically during:
- Post-call summary generation
- SMS intel extraction
- Perplexity research

```javascript
// In extractInboundIntel()
const tags = await extractTags(transcript);
// Returns: ['budget', 'hiring', 'residential']
```

### Manual Tagging

Reps can add/remove tags from:
- Lead Profile page (tag chips below name)
- Intel Edit modal
- Bulk actions on Leads page

---

## Database

```sql
-- Tag definitions
CREATE TABLE IF NOT EXISTS intel_tags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(50) NOT NULL UNIQUE,
  category VARCHAR(50) NOT NULL,
  color VARCHAR(20) DEFAULT 'gray',
  icon VARCHAR(50),
  auto_patterns TEXT[], -- Regex patterns for auto-detection
  usage_count INTEGER DEFAULT 0,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Lead-tag associations
CREATE TABLE IF NOT EXISTS lead_tags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  lead_id UUID REFERENCES leads(id) ON DELETE CASCADE,
  tag_id UUID REFERENCES intel_tags(id) ON DELETE CASCADE,
  source VARCHAR(50), -- 'auto', 'manual', 'ai'
  confidence DECIMAL(3,2), -- 0.00-1.00 for auto-tags
  added_by UUID REFERENCES auth.users(id),
  added_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(lead_id, tag_id)
);

-- Indexes
CREATE INDEX idx_lead_tags_lead ON lead_tags(lead_id);
CREATE INDEX idx_lead_tags_tag ON lead_tags(tag_id);

-- Seed common tags
INSERT INTO intel_tags (name, category, color, auto_patterns) VALUES
('budget', 'objection', 'red', ARRAY['budget', 'expensive', 'cost', 'afford']),
('timing', 'objection', 'orange', ARRAY['not now', 'later', 'next month', 'busy']),
('hiring', 'status', 'green', ARRAY['hiring', 'looking for', 'need workers']),
('residential', 'interest', 'blue', ARRAY['house', 'home', 'residential']),
('commercial', 'interest', 'purple', ARRAY['commercial', 'office', 'warehouse']);
```

---

## API Endpoints

```
GET    /api/tags                    # List all tags
POST   /api/tags                    # Create tag
GET    /api/leads/:id/tags          # Get lead's tags
POST   /api/leads/:id/tags          # Add tag to lead
DELETE /api/leads/:id/tags/:tagId   # Remove tag
GET    /api/leads?tags=hiring,budget # Filter by tags
```

---

## UI Components

### TagChips.jsx
- Display tags on Lead Profile
- Click to filter Leads by tag
- X button to remove (manual tags only)

### TagSelector.jsx
- Dropdown with all available tags
- Grouped by category
- Search/filter tags
- Create new tag inline

### TagFilter.jsx
- Filter bar on Leads page
- Multi-select tags
- AND/OR toggle for multiple tags

---

## Implementation Steps

### Phase 1: Database + API (1.5 hours)
1. [ ] Create migration for intel_tags and lead_tags
2. [ ] Seed common tags
3. [ ] Create tags routes
4. [ ] Add tag filtering to leads endpoint

### Phase 2: Auto-Tagging (1 hour)
1. [ ] Add extractTags() to AI service
2. [ ] Hook into post-call summary
3. [ ] Hook into SMS intel extraction

### Phase 3: Frontend (1.5 hours)
1. [ ] Create TagChips component
2. [ ] Add to LeadProfile
3. [ ] Create TagFilter for Leads page
4. [ ] Add TagSelector to Intel Edit modal

---

## Success Metrics

- 80% of leads have at least 1 tag within a week
- Filtering by tag used 10+ times/day
- Auto-tagging accuracy >85%