# Credits & Limits Implementation - Quick Summary

**Status:** 🚧 READY TO IMPLEMENT  
**Timeline:** 5 weeks  
**Priority:** HIGH

---

## The Big Picture

### What We're Doing
Simplifying the IGNY8 credits and limits system from complex (10+ limits) to simple (4 limits only).

### Core Philosophy
**Keep only 4 hard limits. Everything else = credits.**

---

## The 4 Limits (FINAL)

| Limit | Type | What It Controls |
|-------|------|-----------------|
| **Sites** | Hard | Max sites per account (e.g., 1, 2, 5, unlimited) |
| **Team Users** | Hard | Max team members (e.g., 1, 2, 3, 5) |
| **Keywords** | Hard | Total keywords in workspace (e.g., 100, 1K, 5K, 20K) |
| **Ahrefs Queries** | Monthly | Live keyword research per month (e.g., 0, 50, 200, 500) |

**Everything else (content, images, ideas, etc.) = credits only.**

---

## What Gets REMOVED

### Database Fields to Delete

**From Plan Model:**
- ❌ `max_content_ideas`
- ❌ `max_content_words`
- ❌ `max_images_basic`
- ❌ `max_images_premium`
- ❌ `max_image_prompts`
- ❌ `max_clusters` (consider merging with keywords)

**From Account Model:**
- ❌ `usage_content_ideas`
- ❌ `usage_content_words`
- ❌ `usage_images_basic`
- ❌ `usage_images_premium`
- ❌ `usage_image_prompts`

### Why?
- Confusing for users (double limiting)
- Maintenance overhead
- Credit system already provides control

---

## What Gets ADDED

### New Fields

**Plan Model:**
```python
max_ahrefs_queries = models.IntegerField(default=50)
```

**Account Model:**
```python
usage_ahrefs_queries = models.IntegerField(default=0)
```

### New Feature: Keyword Research

**Two ways to add keywords:**

1. **Browse Pre-Researched Keywords** (FREE)
   - IGNY8's global keyword database
   - Pre-analyzed, ready to use
   - Limited by: `max_keywords` (workspace limit)

2. **Research with Ahrefs** (LIMITED)
   - Live Ahrefs API queries
   - Fresh, custom keyword data
   - Limited by: `max_ahrefs_queries` (monthly limit)

---

## Page Changes

### Plans & Billing Page (Simplified)

**Current Plan Tab - BEFORE:**
- ❌ Credit balance display
- ❌ Usage charts
- ❌ Limit progress bars
- ❌ "Credits used this month" breakdown

**Current Plan Tab - AFTER:**
- ✅ Plan name, price, renewal date
- ✅ Brief summary: "50 articles • 2 sites • 2 users"
- ✅ Upgrade CTA
- ❌ NO detailed usage (moved to Usage page)

### Usage Page (Enhanced)

**NEW Tab Structure:**

1. **Overview** (NEW)
   - Quick stats cards (credits, sites, users, keywords)
   - Period selector (7, 30, 90 days)
   - Top metrics

2. **Your Limits**
   - Only 4 limits with progress bars
   - Sites, Users, Keywords, Ahrefs Queries

3. **Credit Insights** (NEW)
   - Credits by Site
   - Credits by Action Type
   - Credits by Image Quality (basic/quality/premium)
   - Credits by Automation
   - Timeline chart

4. **Activity Log**
   - Detailed transaction history
   - (Renamed from "API Activity")

---

## Key Implementation Tasks

### Backend (Week 1-2)

1. **Remove unused fields**
   - Create migration to drop fields
   - Update models, serializers
   - Remove from LimitService mappings

2. **Add Ahrefs fields**
   - Add to Plan and Account models
   - Add to LimitService mappings
   - Create Ahrefs service

3. **Enforce limits properly**
   - Add keyword limit checks to ALL entry points
   - Add automation credit pre-check
   - Validate before all operations

### Frontend (Week 2-3)

1. **Clean up Plans & Billing**
   - Remove duplicate credit/usage data
   - Keep only financial info

2. **Enhance Usage page**
   - Add Overview tab
   - Add Credit Insights tab with widgets
   - Multi-dimensional breakdowns

3. **Build Keyword Research**
   - Browse panel (existing SeedKeywords)
   - Ahrefs panel (new)
   - Query limit indicator

4. **Update terminology**
   - Remove "API", "operations"
   - Use "actions", "activities"

---

## Validation Requirements

### Must Check BEFORE Every Operation

**All AI Operations:**
```python
# 1. Check credits
CreditService.check_credits(account, estimated_credits)

# 2. Execute
result = ai_service.execute()

# 3. Deduct
CreditService.deduct_credits_for_operation(...)
```

**Keyword Creation:**
```python
# Check limit
LimitService.check_hard_limit(account, 'keywords', count)

# Then create
Keywords.objects.bulk_create([...])
```

**Automation Runs:**
```python
# Estimate total cost
estimated = estimate_automation_cost(config)

# Check BEFORE starting
CreditService.check_credits(account, estimated)

# Then run
execute_automation(config)
```

---

## Success Criteria

### Technical
- [ ] All unused fields removed
- [ ] 4 limits properly enforced
- [ ] Credit checks before ALL operations
- [ ] Automation pre-checks credits
- [ ] No duplicate data across pages

### User Experience
- [ ] Simple 4-limit model is clear
- [ ] Multi-dimensional insights are actionable
- [ ] Keyword research flow is intuitive
- [ ] Error messages are user-friendly
- [ ] Upgrade prompts at right moments

### Business
- [ ] Reduced support questions
- [ ] Higher upgrade conversion
- [ ] Better credit visibility
- [ ] System scales cleanly

---

## Suggested Plan Values

| Plan | Price | Credits/mo | Sites | Users | Keywords | Ahrefs/mo |
|------|-------|-----------|-------|-------|----------|-----------|
| **Free** | $0 | 2,000 | 1 | 1 | 100 | 0 |
| **Starter** | $49 | 10,000 | 2 | 2 | 1,000 | 50 |
| **Growth** | $149 | 40,000 | 5 | 3 | 5,000 | 200 |
| **Scale** | $399 | 120,000 | ∞ | 5 | 20,000 | 500 |

---

## Timeline

**Week 1:** Backend cleanup (remove fields, add Ahrefs)  
**Week 2:** Enforcement (keyword limits, automation checks)  
**Week 3:** Frontend cleanup (remove duplicates, update UI)  
**Week 4:** New features (Credit Insights, Keyword Research)  
**Week 5:** Testing & Production deployment

---

## Files to Review

**Full Implementation Plan:**
- `docs/plans/CREDITS-LIMITS-IMPLEMENTATION-PLAN.md`

**Current System Docs:**
- `docs/10-MODULES/BILLING.md`
- `docs/40-WORKFLOWS/CREDIT-SYSTEM.md`

**Code:**
- Backend: `backend/igny8_core/auth/models.py`
- Backend: `backend/igny8_core/business/billing/services/limit_service.py`
- Frontend: `frontend/src/pages/account/PlansAndBillingPage.tsx`
- Frontend: `frontend/src/pages/account/UsageAnalyticsPage.tsx`

---

**Status:** ✅ READY FOR TEAM REVIEW AND IMPLEMENTATION

**Next Step:** Schedule implementation kickoff meeting with backend, frontend, and QA leads.