# RateRight Growth Engine - System Overview

> **Generated:** January 28, 2026
> **Purpose:** Comprehensive overview of the entire system for quick context recovery

---

## What This Is

RateRight Growth Engine is an AI-powered sales CRM and lead management platform for RateRight (a contractor marketplace). Built mobile-first with React frontend and Express.js backend, it combines AI-powered sales assistance with Twilio SMS/Voice integration to help sales teams work smarter.

---

## Tech Stack

| Layer | Technology |
|-------|------------|
| **Backend** | Express.js + Node.js (Railway) |
| **Frontend** | React + Vite + Tailwind CSS |
| **Database** | Supabase PostgreSQL |
| **AI** | OpenAI GPT-4o, Whisper, Deepgram Nova-2, Perplexity |
| **Communications** | Twilio SMS + Voice SDK |
| **Realtime** | Supabase Realtime subscriptions |
| **Notifications** | Slack Webhooks |
| **Bot Integration** | Telegram (Clawdbot) |
| **Business Hub** | Notion API |

---

## Core Philosophy: 0.1% Quality Standard

Every feature is built to the standard: "Would the top 0.1% best CRM in the world do it this way?"

**Quality Check Before Marking Complete:**
- Would the best CRM do it this way?
- Is there friction?
- Could AI make it smarter?
- One click when it could be zero?

---

## Feature Status Summary

| Rating | Count | Description |
|--------|-------|-------------|
| **0.1%** | 64 | Elite quality, industry-leading |
| **Good** | 35 | Solid, working well |
| **Basic** | 6 | Functional but needs polish |
| **Planned** | 5 | Designed, not yet built |

**Total: 110 features tracked**

---

## Core Features

### 1. Lead Management
- Full CRUD operations with soft deletes
- Lead scoring (0-100) with AI-powered predictive scoring
- Score tiers: Hot (70+), Warm (50-69), Cool (20-49), Cold (0-19)
- Trade/category classification
- 8-stage sales pipeline tracking

### 2. Smart Call List
The AI-powered call prioritization system ranks leads using:

| Factor | Weight | Description |
|--------|--------|-------------|
| Urgency | 35% | Hot leads, stale leads, time-sensitive |
| Intent Signals | 25% | Positive SMS, engagement patterns |
| Timing | 20% | Best time to call based on history |
| Pattern Match | 15% | Similar to past conversions |
| Base Score | 5% | Lead score |

**Features:**
- "Why This Lead" badges showing AI reasoning
- Auto-refresh every 5 minutes
- Pattern-boosted leads get 1.5x priority
- Callback scheduling integration

### 3. Communications Hub

**SMS:**
- Send/receive via Twilio
- Intent classification (positive/negative/question/unclear)
- Template system with variable substitution
- Auto-reply for after-hours
- SMS Sequences v2 with stage-based automation

**In-App Calling:**
- Twilio Voice SDK browser calling
- Auto-transcription (Deepgram/Web Speech API)
- Post-call AI summary generation
- Call outcome logging with one-tap options

### 4. AI Sales Tools

| Tool | Description |
|------|-------------|
| **Intel Briefs** | Pre-call preparation with similar wins |
| **Post-Call Summary** | Auto-generated when call ends |
| **Message Drafting** | AI-powered SMS writing |
| **Live Copilot** | Real-time transcription + objection handling |
| **Voice Assistant** | Natural language commands + idea capture |
| **Predictive Scoring** | AI conversion probability |
| **Script Recommendation** | Suggests best approach based on lead stage |

### 5. Learning System

The system continuously learns from team interactions:

- **Conversion Patterns:** Auto-captures full journey when leads convert
- **Objection Responses:** Tracks which responses work, effectiveness scores
- **Suggestion Feedback:** Thumbs up/down on AI suggestions
- **Proven Responses:** AI uses real data to improve over time
- **Auto-Tune:** Winning patterns automatically boost matching leads

### 6. Battleground Gamification

**Current Features (0.1%):**
- Live leaderboard with real-time XP tracking
- Hall of Fame with historical achievements
- Personal stats and progress tracking
- Team Pulse activity feed
- Achievement badges and levels

**Planned (v2):**
- XP Duels with AI odds calculation
- Manager Challenges with real stakes
- Sound/visual celebrations
- Simplified daily view

### 7. Quality Audit System

**Daily automated testing at 6am AEST:**
- 28 tests across 5 categories
- Results posted to Slack #growth-engine-alerts
- Categories: Data Health, AI Quality, Comms, Learning, Feature

### 8. Weekly Intelligence Report

**Monday 7am AEST to Slack:**
- Best performing trades
- Best contact times
- Winning channels analysis
- Touchpoint patterns
- Auto-tune recommendations

---

## Database Architecture

### Core Tables
- `leads` - Lead records with scoring and status
- `communications` - SMS/call history
- `callbacks` - Scheduled callback queue
- `users` - Team member profiles

### AI/Learning Tables
- `copilot_sessions` - Live transcription sessions
- `ai_insights` - Generated insights
- `winning_patterns` - Auto-tune patterns
- `conversion_patterns` - Full conversion journeys
- `objection_responses` - Response effectiveness tracking
- `suggestion_feedback` - Thumbs up/down on AI suggestions

### Gamification Tables
- `user_xp_history` - XP earning events
- `user_achievements` - Unlocked achievements
- `hall_of_fame` - Historical records

---

## Key Services

| Service | Location | Purpose |
|---------|----------|---------|
| `ai.js` | `src/services/` | All AI logic (GPT-4o integration) |
| `learning.js` | `src/services/` | Learning system (patterns, feedback) |
| `callListRanker.js` | `src/services/` | Smart call list prioritization |
| `slack.js` | `src/services/` | Slack notifications |
| `qualityAudit.js` | `src/jobs/` | Daily quality audit tests |
| `weeklyReport.js` | `src/jobs/` | Weekly insights generation |

---

## Frontend Architecture

### Key Pages
- **Dashboard** - Overview with key metrics
- **Call List** - AI-prioritized leads to call
- **Inbox** - SMS conversation management
- **Lead Profile** - Full lead details with timeline
- **Battleground** - Gamification hub
- **Callbacks** - Scheduled callback management

### Key Contexts
- `CallContext.jsx` - Auto-transcription management
- `RealtimeContext.jsx` - Supabase realtime subscriptions
- `AuthContext.jsx` - User authentication state

### Real-Time Features
- Live SMS notifications with audio alert
- Instant dashboard refresh on new activity
- Visual indicators (green wifi icon, pulsing badge)
- "NEW MESSAGE" banner on inbound SMS

---

## Deployment

### Production URLs
- **API:** https://rateright-growth-production.up.railway.app
- **Database:** https://memscjotxrzqnhrvnnkc.supabase.co
- **Twilio Phone:** +61 468 087 171

### Deploy Process
```bash
# Build frontend
cd admin && npm run build

# Copy to public folder
# Copy admin/dist/* to public/

# Push to GitHub (Railway auto-deploys)
git push origin main
```

---

## Team Users

| Name | Role | Primary Features |
|------|------|------------------|
| Tony McCabe | Sales Director | Call List, Call Logging |
| Angelica | GM Remote Operations | Inbox, Lead Profiles |
| Michael | Founder | Dashboard, Strategy |

---

## Upcoming Features

### Ready for Build
1. **Pre-Call Briefing Page** - Full-screen call prep with AI script recommendation
2. **Nav Cleanup** - Context-aware dashboard messaging
3. **PWA Mobile Support** - Install prompts, offline support, push notifications

### Planned (Future)
1. **Battleground v2** - XP Duels, Manager Challenges
2. **AI Sales Brain** - Unified intelligence API
3. **Personal Coaching AI** - Role-specific improvement suggestions
4. **Automated SMS Sequences** - Stage-based automation

---

## Documentation Map

| File | Purpose |
|------|---------|
| `CLAUDE.md` | Project overview and AI assistant instructions |
| `docs/SYSTEM-INTEL.md` | Feature status tracker + priorities |
| `docs/SYSTEM-OVERVIEW.md` | This file - comprehensive overview |
| `docs/CODEBASE_MAP.md` | File locations and architecture |
| `docs/LESSONS.md` | Hard-won knowledge and gotchas |
| `docs/ROADMAP.md` | Phase-by-phase completion tracking |
| `BUILD-GUIDE.md` | Detailed build documentation |
| `supabase/PENDING_MIGRATIONS.md` | Database migration tracking |

---

## Context Recovery Order

When starting a new session, read in this order:
1. `CLAUDE.md` - Project overview and patterns
2. `docs/LESSONS.md` - Hard-won knowledge, gotchas
3. `docs/SYSTEM-INTEL.md` - Feature status + priorities
4. `BUILD-GUIDE.md` - What's been built
5. `docs/CODEBASE_MAP.md` - File locations
6. `supabase/PENDING_MIGRATIONS.md` - Pending database changes

---

*Last Updated: January 2026*