23 KiB
23 KiB
System Architecture - Before vs After
BEFORE (Complex & Confusing)
┌─────────────────────────────────────────────────────────────────┐
│ PLAN MODEL (BEFORE) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Hard Limits (Never Reset): │
│ ├─ max_sites ✅ Keep │
│ ├─ max_users ✅ Keep │
│ ├─ max_keywords ✅ Keep │
│ └─ max_clusters ❌ Remove │
│ │
│ Monthly Limits (Reset Every Month): │
│ ├─ max_content_ideas ❌ Remove │
│ ├─ max_content_words ❌ Remove │
│ ├─ max_images_basic ❌ Remove │
│ ├─ max_images_premium ❌ Remove │
│ └─ max_image_prompts ❌ Remove │
│ │
│ Credits: │
│ └─ included_credits ✅ Keep │
│ │
│ TOTAL LIMITS: 10 fields ❌ TOO COMPLEX │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ ACCOUNT MODEL (BEFORE) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Credits: │
│ └─ credits ✅ Keep │
│ │
│ Monthly Usage Tracking: │
│ ├─ usage_content_ideas ❌ Remove │
│ ├─ usage_content_words ❌ Remove │
│ ├─ usage_images_basic ❌ Remove │
│ ├─ usage_images_premium ❌ Remove │
│ └─ usage_image_prompts ❌ Remove │
│ │
│ Period Tracking: │
│ ├─ usage_period_start ✅ Keep │
│ └─ usage_period_end ✅ Keep │
│ │
│ TOTAL USAGE FIELDS: 5 ❌ UNNECESSARY │
│ │
└─────────────────────────────────────────────────────────────────┘
USER CONFUSION:
"I have 5000 credits but can't generate content because I hit my
monthly word limit? This makes no sense!"
AFTER (Simple & Clear)
┌─────────────────────────────────────────────────────────────────┐
│ PLAN MODEL (AFTER) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ THE ONLY 4 LIMITS: │
│ ├─ max_sites (e.g., 1, 2, 5, unlimited) │
│ ├─ max_users (e.g., 1, 2, 3, 5) │
│ ├─ max_keywords (e.g., 100, 1K, 5K, 20K) │
│ └─ max_ahrefs_queries (e.g., 0, 50, 200, 500) [NEW] │
│ │
│ Credits: │
│ └─ included_credits (e.g., 2K, 10K, 40K, 120K) │
│ │
│ TOTAL LIMITS: 4 fields ✅ SIMPLE & CLEAR │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ ACCOUNT MODEL (AFTER) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Credits: │
│ └─ credits (current balance) │
│ │
│ Monthly Usage Tracking: │
│ └─ usage_ahrefs_queries (only 1 tracker needed) [NEW] │
│ │
│ Period Tracking: │
│ ├─ usage_period_start │
│ └─ usage_period_end │
│ │
│ TOTAL USAGE FIELDS: 1 ✅ CLEAN │
│ │
└─────────────────────────────────────────────────────────────────┘
USER CLARITY:
"I have 5000 credits. I can use them for whatever I need -
articles, images, ideas. Simple!"
Page Structure - Before vs After
BEFORE (Duplicate Data Everywhere)
┌───────────────────────────────────────────────────────────────────┐
│ PLANS & BILLING PAGE │
├───────────────────────────────────────────────────────────────────┤
│ Tab 1: Current Plan │
│ ├─ Plan name, price ✅ │
│ ├─ Credit balance ⚠️ DUPLICATE (also in Usage) │
│ ├─ Credits used ⚠️ DUPLICATE (also in Usage) │
│ ├─ Usage charts ⚠️ DUPLICATE (also in Usage) │
│ └─ Limit bars ⚠️ DUPLICATE (also in Usage) │
│ │
│ Tab 2: Upgrade │
│ └─ Pricing table ✅ │
│ │
│ Tab 3: History │
│ ├─ Invoices ✅ │
│ └─ Transactions ⚠️ PARTIAL DUPLICATE (also in Usage) │
└───────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────┐
│ USAGE PAGE │
├───────────────────────────────────────────────────────────────────┤
│ Tab 1: Limits & Usage │
│ ├─ Credit balance ⚠️ DUPLICATE (also in Plans & Billing) │
│ ├─ Credits used ⚠️ DUPLICATE (also in Plans & Billing) │
│ ├─ Limit bars ⚠️ DUPLICATE (also in Plans & Billing) │
│ └─ 10+ limit types ❌ TOO MANY │
│ │
│ Tab 2: Credit History │
│ └─ Transactions ⚠️ PARTIAL DUPLICATE (also in Plans & Billing)│
│ │
│ Tab 3: API Activity ❌ TECHNICAL TERMINOLOGY │
│ └─ Operation logs │
└───────────────────────────────────────────────────────────────────┘
AFTER (Clear Separation)
┌───────────────────────────────────────────────────────────────────┐
│ PLANS & BILLING PAGE (Financial Focus) │
├───────────────────────────────────────────────────────────────────┤
│ Tab 1: Current Plan │
│ ├─ Plan name, price, renewal date ✅ │
│ ├─ Brief summary: "50 articles • 2 sites • 2 users" ✅ │
│ ├─ Upgrade CTA ✅ │
│ └─ ❌ NO usage details (moved to Usage page) │
│ │
│ Tab 2: Upgrade Plan │
│ └─ Pricing table ✅ │
│ │
│ Tab 3: Billing History │
│ ├─ Invoices ✅ │
│ ├─ Payment methods ✅ │
│ └─ Credit purchases ✅ (financial transactions only) │
└───────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────┐
│ USAGE PAGE (Consumption Tracking) │
├───────────────────────────────────────────────────────────────────┤
│ Tab 1: Overview [NEW] │
│ ├─ Quick stats: Credits, Sites, Users, Keywords ✅ │
│ ├─ Period selector: 7/30/90 days ✅ │
│ └─ Top metrics for selected period ✅ │
│ │
│ Tab 2: Your Limits │
│ └─ ONLY 4 limits with progress bars ✅ │
│ ├─ Sites (e.g., 2 / 5) │
│ ├─ Users (e.g., 2 / 3) │
│ ├─ Keywords (e.g., 847 / 1,000) │
│ └─ Ahrefs Queries (e.g., 23 / 50 this month) │
│ │
│ Tab 3: Credit Insights [NEW] │
│ ├─ Credits by Site 📊 │
│ ├─ Credits by Action Type 📊 │
│ ├─ Credits by Image Quality 📊 │
│ ├─ Credits by Automation 📊 │
│ └─ Timeline chart 📈 │
│ │
│ Tab 4: Activity Log (renamed from "API Activity") │
│ └─ Detailed transaction history ✅ │
└───────────────────────────────────────────────────────────────────┘
Credit Flow - Before vs After
BEFORE (Double Limiting)
User wants to generate content
↓
Check 1: Do they have credits? ✅ Yes, 5000 credits
↓
Check 2: Have they hit monthly word limit? ❌ YES, 100K/100K
↓
BLOCKED! "You've reached your monthly word limit"
↓
User: "But I have 5000 credits left! 😤"
AFTER (Simple Credit-Based)
User wants to generate content
↓
Check: Do they have credits? ✅ Yes, 5000 credits
↓
Generate content (costs ~50 credits based on tokens)
↓
Deduct credits: 5000 - 50 = 4950 remaining
↓
User: "Simple! I can use my credits however I want 😊"
Keyword Research - NEW Structure
┌───────────────────────────────────────────────────────────────────┐
│ KEYWORD RESEARCH PAGE [NEW] │
├───────────────────────────────────────────────────────────────────┤
│ │
│ Tab Selector: │
│ [Browse Pre-Researched] [Research with Ahrefs - 42/50 left] │
│ │
├───────────────────────────────────────────────────────────────────┤
│ Option 1: Browse Pre-Researched Keywords (FREE) │
│ ─────────────────────────────────────────────── │
│ • Global IGNY8 keyword database │
│ • Filter by: Industry, Sector, Country │
│ • Pre-analyzed metrics: Volume, Difficulty, Opportunity │
│ • Free to browse and add │
│ • Adds to workspace (counts toward max_keywords) │
│ │
│ [Industry ▼] [Sector ▼] [Country ▼] [Search...] │
│ │
│ Results: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Keyword │ Volume │ Diff │ Score │ [Add] │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ digital marketing │ 45K │ 65 │ 88/100 │ [Add] │ │
│ │ content strategy │ 12K │ 42 │ 92/100 │ [Add] │ │
│ │ seo optimization │ 33K │ 58 │ 85/100 │ [Add] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
├───────────────────────────────────────────────────────────────────┤
│ Option 2: Research with Ahrefs (LIMITED) │
│ ─────────────────────────────────────────── │
│ • Live Ahrefs API queries │
│ • Fresh, custom keyword data │
│ • Monthly limit: 42 / 50 queries remaining ⚠️ │
│ • Resets: February 1, 2026 │
│ │
│ [Enter seed keyword...] [Research Keywords] │
│ │
│ ⚠️ Warning: Each search uses 1 query from your monthly limit │
│ │
│ Results (if searched): │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Keyword │ Volume │ Diff │ CPC │ [Add] │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ ai content tools │ 8.9K │ 48 │ $4.50│ [Add] │ │
│ │ automated writing │ 3.2K │ 35 │ $3.80│ [Add] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────┘
Enforcement Points
Backend Validation (REQUIRED at these locations)
1. Keyword Creation
├─ Manual keyword creation form
├─ SeedKeyword import (from Browse tab)
├─ Ahrefs import (from Research tab)
├─ CSV/Excel bulk import
└─ API endpoint: POST /api/v1/keywords/
✅ Must check: LimitService.check_hard_limit(account, 'keywords', count)
2. Site Creation
└─ API endpoint: POST /api/v1/sites/
✅ Must check: LimitService.check_hard_limit(account, 'sites', 1)
3. User Invitation
└─ API endpoint: POST /api/v1/users/invite/
✅ Must check: LimitService.check_hard_limit(account, 'users', 1)
4. Ahrefs Query
└─ API endpoint: POST /api/v1/keywords/ahrefs/search/
✅ Must check: LimitService.check_monthly_limit(account, 'ahrefs_queries', 1)
✅ Must increment: LimitService.increment_usage(account, 'ahrefs_queries', 1)
5. All AI Operations (Content, Images, Ideas, etc.)
✅ Must check: CreditService.check_credits(account, estimated_credits)
✅ Must deduct: CreditService.deduct_credits_for_operation(...)
6. Automation Runs
✅ Must pre-check: CreditService.check_credits(account, estimated_total)
✅ Each stage deducts: CreditService.deduct_credits_for_operation(...)
Error Messages (User-Friendly)
OLD (Technical)
HTTP 402 - HardLimitExceededError:
max_keywords limit reached (1000/1000)
NEW (User-Friendly)
┌─────────────────────────────────────────────────────────────┐
│ ⚠️ Keyword Limit Reached │
├─────────────────────────────────────────────────────────────┤
│ │
│ You've reached your keyword limit of 1,000 keywords. │
│ │
│ Current workspace: 1,000 keywords │
│ Your plan limit: 1,000 keywords │
│ │
│ To add more keywords, you can: │
│ • Delete unused keywords to free up space │
│ • Upgrade to Growth plan (5,000 keywords) │
│ │
│ [Delete Keywords] [Upgrade Plan] [Cancel] │
│ │
└─────────────────────────────────────────────────────────────┘
End of Visual Reference
See CREDITS-LIMITS-IMPLEMENTATION-PLAN.md for complete details.