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