357 lines
23 KiB
Markdown
357 lines
23 KiB
Markdown
# 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.
|