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