igny8/docs/plans/IMPLEMENTATION-SUMMARY.md

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:

max_ahrefs_queries = models.IntegerField(default=50)

Account Model:

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:

# 1. Check credits
CreditService.check_credits(account, estimated_credits)

# 2. Execute
result = ai_service.execute()

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

Keyword Creation:

# Check limit
LimitService.check_hard_limit(account, 'keywords', count)

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

Automation Runs:

# 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.