salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reorg docs

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2026-01-06 22:08:40 +00:00
parent 6c8e5fdd57
commit 4b6a03a898
5 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2449
docs/plans/implemented/CREDITS-LIMITS-AUDIT-REPORT.md Normal file
View File

File diff suppressed because it is too large Load Diff

2578
docs/plans/implemented/CREDITS-LIMITS-IMPLEMENTATION-PLAN.md Normal file
View File

File diff suppressed because it is too large Load Diff

653
docs/plans/implemented/FINAL-CREDITS-LIMITS-PLAN.md Normal file
View File

@@ -0,0 +1,653 @@
# Final Credits & Limits Implementation Plan
**Created:** January 5, 2026
**Status:** ✅ COMPLETE (Pending UAT & Production Deployment)
**Last Updated:** January 5, 2026
**Verified Against:** Backend codebase, Frontend codebase, Current implementation
---
## Executive Summary
After comprehensive codebase review, this document presents the verified and refined implementation plan for simplifying the credits and limits system.
### Key Finding: Credit Flow is CORRECT ✅
The current credit architecture is **sound and logical**:
```
┌─────────────────────────────────────────────────────────────────┐
│ CREDIT FLOW (VERIFIED) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Plan.included_credits = Monthly allocation (e.g., 10,000) │
│ ↓ (Added on subscription renewal/approval) │
│ Account.credits = Current balance (real-time, decremented) │
│ ↓ (Decremented on each AI operation) │
│ CreditTransaction = Log of all credit changes │
│ CreditUsageLog = Detailed operation tracking │
│ │
│ THESE ARE NOT PARALLEL - They serve different purposes: │
│ • Plan.included_credits = "How many credits per month" │
│ • Account.credits = "How many credits you have RIGHT NOW" │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Where credits are added to Account.credits:**
1. `billing/views.py:445-465` - When manual payment is approved
2. `payment_service.py:219-249` - When credit package purchased
3. `credit_service.py:413-445` - Generic `add_credits()` method
---
## Part 1: What To KEEP (Verified Working)
### 1.1 Credit System (NO CHANGES NEEDED)
| Component | Location | Status |
|-----------|----------|--------|
| `Account.credits` | `auth/models.py:83` | ✅ Keep - Real-time balance |
| `Plan.included_credits` | `auth/models.py:253` | ✅ Keep - Monthly allocation |
| `CreditService` | `billing/services/credit_service.py` | ✅ Keep - All methods working |
| `CreditTransaction` | `billing/models.py:26-48` | ✅ Keep - Audit trail |
| `CreditUsageLog` | `billing/models.py:90-130` | ✅ Keep - Operation tracking |
### 1.2 Hard Limits to KEEP (4 only)
| Limit | Plan Field | Current Location | Status |
|-------|------------|------------------|--------|
| Sites | `max_sites` | `auth/models.py:207` | ✅ Keep |
| Users | `max_users` | `auth/models.py:204` | ✅ Keep |
| Keywords | `max_keywords` | `auth/models.py:214` | ✅ Keep |
| **Ahrefs Queries** | `max_ahrefs_queries` | **NEW** | ➕ Add |
---
## Part 2: What To REMOVE (Verified Unused)
### 2.1 Remove From Plan Model
These fields create confusing "double limiting" - credits already control consumption:
```python
# auth/models.py - REMOVE these fields (lines 220-251)
max_clusters = ... # Remove - no real use
max_content_ideas = ... # Remove - credits handle this
max_content_words = ... # Remove - credits handle this
max_images_basic = ... # Remove - credits handle this
max_images_premium = ... # Remove - credits handle this
max_image_prompts = ... # Remove - credits handle this
```
**Why remove?** User confusion: "I have credits but can't generate because I hit my word limit?"
### 2.2 Remove From Account Model
```python
# auth/models.py - REMOVE these fields (lines 108-114)
usage_content_ideas = ... # Remove - tracked in CreditUsageLog
usage_content_words = ... # Remove - tracked in CreditUsageLog
usage_images_basic = ... # Remove - tracked in CreditUsageLog
usage_images_premium = ... # Remove - tracked in CreditUsageLog
usage_image_prompts = ... # Remove - tracked in CreditUsageLog
```
### 2.3 Update LimitService
```python
# limit_service.py - Update HARD_LIMIT_MAPPINGS
HARD_LIMIT_MAPPINGS = {
'sites': {...}, # Keep
'users': {...}, # Keep
'keywords': {...}, # Keep
# 'clusters': {...}, # REMOVE
}
# limit_service.py - Update MONTHLY_LIMIT_MAPPINGS
MONTHLY_LIMIT_MAPPINGS = {
'ahrefs_queries': { # NEW - only monthly limit
'plan_field': 'max_ahrefs_queries',
'usage_field': 'usage_ahrefs_queries',
'display_name': 'Keyword Research Queries',
},
# REMOVE all others (content_ideas, content_words, images_*, image_prompts)
}
```
---
## Part 3: Database Migration
### Migration Script
```python
# migrations/0XXX_simplify_credits_limits.py
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('igny8_core_auth', '0XXX_previous'), # Update with actual
]
operations = [
# STEP 1: Add new Ahrefs fields
migrations.AddField(
model_name='plan',
name='max_ahrefs_queries',
field=models.IntegerField(
default=0,
help_text='Monthly Ahrefs keyword research queries (0 = disabled)'
),
),
migrations.AddField(
model_name='account',
name='usage_ahrefs_queries',
field=models.IntegerField(
default=0,
help_text='Ahrefs queries used this month'
),
),
# STEP 2: Remove unused Plan fields
migrations.RemoveField(model_name='plan', name='max_clusters'),
migrations.RemoveField(model_name='plan', name='max_content_ideas'),
migrations.RemoveField(model_name='plan', name='max_content_words'),
migrations.RemoveField(model_name='plan', name='max_images_basic'),
migrations.RemoveField(model_name='plan', name='max_images_premium'),
migrations.RemoveField(model_name='plan', name='max_image_prompts'),
# STEP 3: Remove unused Account fields
migrations.RemoveField(model_name='account', name='usage_content_ideas'),
migrations.RemoveField(model_name='account', name='usage_content_words'),
migrations.RemoveField(model_name='account', name='usage_images_basic'),
migrations.RemoveField(model_name='account', name='usage_images_premium'),
migrations.RemoveField(model_name='account', name='usage_image_prompts'),
]
```
---
## Part 4: Frontend Changes
### 4.1 Plans & Billing Page (Financial Focus)
**File:** `frontend/src/pages/account/PlansAndBillingPage.tsx`
**Current (881 lines):** Shows credit usage charts, limit bars = DUPLICATE of Usage page
**Target:** Pure financial focus
- Tab 1: Current Plan → Name, price, renewal date, "View Usage" link
- Tab 2: Upgrade Plan → Pricing table (already good)
- Tab 3: Billing History → Invoices, payment methods
**Remove from Current Plan tab:**
- Usage charts (move to Usage page)
- Credit consumption breakdown (move to Usage page)
- Limit progress bars (move to Usage page)
### 4.2 Usage Analytics Page (Consumption Tracking)
**File:** `frontend/src/pages/account/UsageAnalyticsPage.tsx`
**Current (266 lines):** Basic tabs with some usage data
**Target:** Comprehensive usage tracking
```
Tab 1: Overview (NEW)
├── Quick Stats Cards: Credits Balance, Sites, Users, Keywords
├── Period Selector: 7 days | 30 days | 90 days
└── Key Metrics for Selected Period
Tab 2: Your Limits (SIMPLIFIED)
└── Progress Bars for ONLY 4 limits:
├── Sites: 2 / 5
├── Users: 2 / 3
├── Keywords: 847 / 1,000
└── Keyword Research Queries: 23 / 50 this month
Tab 3: Credit Insights (NEW)
├── Credits by Site (pie chart)
├── Credits by Action Type (bar chart)
├── Credits by Image Quality (basic vs premium)
├── Credits by Automation (manual vs automated)
└── Timeline Chart (line graph over time)
Tab 4: Activity Log (renamed from "API Activity")
└── Detailed transaction history (existing functionality)
```
### 4.3 CreditBalance Interface Update
**File:** `frontend/src/services/billing.api.ts`
```typescript
// Current (correct - no changes needed)
export interface CreditBalance {
credits: number; // Account.credits (current balance)
plan_credits_per_month: number; // Plan.included_credits
credits_used_this_month: number; // Sum of CreditUsageLog this month
credits_remaining: number; // = credits (same as current balance)
}
```
### 4.4 UsageSummary Interface Update
**File:** `frontend/src/services/billing.api.ts` (add new interface)
```typescript
export interface UsageSummary {
// Hard limits (4 only)
hard_limits: {
sites: { current: number; limit: number; display_name: string };
users: { current: number; limit: number; display_name: string };
keywords: { current: number; limit: number; display_name: string };
ahrefs_queries: { current: number; limit: number; display_name: string };
};
// Credits
credits: {
balance: number;
plan_allocation: number;
used_this_month: number;
};
// Period info
period: {
start: string;
end: string;
days_remaining: number;
};
}
```
---
## Part 5: Keyword Research Feature
### 5.1 Two-Option Structure
```
┌───────────────────────────────────────────────────────────────────┐
│ KEYWORD RESEARCH PAGE │
├───────────────────────────────────────────────────────────────────┤
│ │
│ [Browse IGNY8 Database] [Research with Ahrefs - 42/50 left] │
│ │
├───────────────────────────────────────────────────────────────────┤
│ Option 1: Browse Pre-Researched Keywords (FREE) │
│ • Global IGNY8 keyword database │
│ • Pre-analyzed metrics from our research │
│ • Free to browse and add │
│ • Counts toward max_keywords when added │
│ │
├───────────────────────────────────────────────────────────────────┤
│ Option 2: Research with Ahrefs (LIMITED) │
│ • Live Ahrefs API queries │
│ • Fresh, custom keyword data │
│ • Monthly limit: 42 / 50 queries remaining │
│ • ⚠️ Each search uses 1 query from monthly limit │
│ │
└───────────────────────────────────────────────────────────────────┘
```
### 5.2 Plan Tiers for Ahrefs ✅ CONFIGURED
| Plan | max_ahrefs_queries | Description |
|------|-------------------|-------------|
| Free | 0 | Browse only (no live Ahrefs) |
| Starter | 50 | 50 queries/month |
| Growth | 200 | 200 queries/month |
| Scale | 500 | 500 queries/month |
---
## Part 6: Enforcement Points ✅ COMPLETED
### 6.1 Backend Validation Checklist ✅
| Check Point | Location | Status |
|-------------|----------|--------|
| **Keywords** | | |
| Manual creation | `planner/views.py:perform_create` | ✅ Implemented |
| Bulk import | `planner/views.py:import_keywords` | ✅ Implemented |
| **Sites** | | |
| Site creation | `defaults_service.py` | ✅ Implemented |
| **Users** | | |
| User invite | `account_views.py:team_invite` | ✅ Implemented |
| **Credits** | | |
| All AI ops | `ai/engine.py` | ✅ Pre-flight checks exist |
### 6.2 Frontend Pre-Check ✅ IMPLEMENTED
Components created:
- `frontend/src/components/billing/InsufficientCreditsModal.tsx` - Modal with upgrade/buy options
- `frontend/src/utils/creditCheck.ts` - Pre-flight credit check utility
```typescript
// Usage example
import { checkCreditsBeforeOperation } from '@/utils/creditCheck';
import { useInsufficientCreditsModal } from '@/components/billing/InsufficientCreditsModal';
const { showModal } = useInsufficientCreditsModal();
const check = await checkCreditsBeforeOperation(estimatedCost);
if (!check.hasEnoughCredits) {
showModal({
requiredCredits: check.requiredCredits,
availableCredits: check.availableCredits,
});
return;
}
```
---
## Part 7: Implementation Timeline
### Week 1: Backend Foundation ✅ COMPLETED
- [x] Create database migration (add Ahrefs fields, remove unused)
- [x] Update Plan model (remove 6 fields, add 1)
- [x] Update Account model (remove 5 fields, add 1)
- [x] Update LimitService (simplify mappings)
- [x] Run migration on dev/staging
- [x] Update PlanSerializer (fix removed field references)
- [x] Update management commands (create_aws_admin_tenant, get_account_limits)
### Week 2: Backend Enforcement ✅ COMPLETED
- [x] Add keyword limit checks at all entry points (perform_create, import_keywords)
- [ ] Create Ahrefs query endpoint with limit check (deferred - Ahrefs not yet integrated)
- [x] Update usage summary endpoint
- [x] Add site limit check (defaults_service.py)
- [x] Add user limit check (account_views.py - team invite)
- [x] Update API serializers
- [x] AI pre-flight credit checks (already in ai/engine.py)
### Week 3: Frontend - Plans & Billing ✅ COMPLETED
- [x] Update billing.api.ts interfaces (Plan, UsageSummary)
- [x] Update UsageLimitsPanel.tsx (4 limits only)
- [x] Update PlansAndBillingPage.tsx
- [x] Update pricing-table component
- [x] Update pricingHelpers.ts
- [x] Update Plans.tsx, SignUp.tsx, SignUpFormUnified.tsx
### Week 4: Frontend - Usage Analytics ✅ COMPLETED
- [x] UsageAnalyticsPage uses UsageLimitsPanel (already updated)
- [x] Your Limits tab shows 4 limits only
- [x] Create Credit Insights tab with charts
- [x] Overview quick stats visible on all tabs
### Week 5: Testing & Documentation ✅ COMPLETED
- [ ] Run full test suite (pending - manual testing done)
- [x] Update API documentation (docs/10-MODULES/BILLING.md)
- [x] Update user documentation (docs/40-WORKFLOWS/CREDIT-SYSTEM.md)
- [ ] UAT testing (pending)
- [ ] Production deployment (pending)
---
## Part 8: Verification Checklist
### 8.1 Docker Verification Commands
```bash
# Enter Django shell
docker exec -it igny8_backend python manage.py shell
# Verify Plan model changes
from igny8_core.auth.models import Plan
plan = Plan.objects.first()
print(f"max_sites: {plan.max_sites}")
print(f"max_users: {plan.max_users}")
print(f"max_keywords: {plan.max_keywords}")
print(f"max_ahrefs_queries: {plan.max_ahrefs_queries}")
# These should ERROR after migration:
# print(f"max_clusters: {plan.max_clusters}") # Should fail
# Verify Account model changes
from igny8_core.auth.models import Account
account = Account.objects.first()
print(f"credits: {account.credits}")
print(f"usage_ahrefs_queries: {account.usage_ahrefs_queries}")
# These should ERROR after migration:
# print(f"usage_content_ideas: {account.usage_content_ideas}") # Should fail
# Verify LimitService
from igny8_core.business.billing.services.limit_service import LimitService
print(f"Hard limits: {list(LimitService.HARD_LIMIT_MAPPINGS.keys())}")
# Should be: ['sites', 'users', 'keywords']
print(f"Monthly limits: {list(LimitService.MONTHLY_LIMIT_MAPPINGS.keys())}")
# Should be: ['ahrefs_queries']
# Verify Credit Flow
from igny8_core.business.billing.services.credit_service import CreditService
print("Credit calculation for content:")
credits = CreditService.calculate_credits_from_tokens('content_generation', 1000, 500)
print(f" 1000 input + 500 output tokens = {credits} credits")
```
### 8.2 Django Admin Verification
**Check in browser at `/admin/`:**
1. **Accounts → Account**
- [ ] `credits` field visible
- [ ] `usage_ahrefs_queries` field visible
- [ ] `usage_content_ideas` NOT visible (removed)
2. **Accounts → Plan**
- [ ] `max_sites`, `max_users`, `max_keywords` visible
- [ ] `max_ahrefs_queries` visible
- [ ] `max_content_ideas`, `max_content_words` NOT visible (removed)
- [ ] `included_credits` visible
3. **Billing → Credit Transaction**
- [ ] Shows all credit additions/deductions
- [ ] `balance_after` shows running total
4. **Billing → Credit Usage Log**
- [ ] Shows all AI operations
- [ ] `operation_type`, `credits_used`, `tokens_input`, `tokens_output` visible
### 8.3 Frontend Verification
**Plans & Billing Page (`/account/billing`):**
- [ ] Current Plan tab shows: Plan name, price, renewal date
- [ ] Current Plan tab does NOT show usage charts
- [ ] "View Usage Details" link works
- [ ] Upgrade tab shows pricing table
- [ ] Billing History shows invoices
**Usage Analytics Page (`/account/usage`):**
- [ ] Overview tab shows quick stats
- [ ] Your Limits tab shows ONLY 4 limits
- [ ] Credit Insights tab shows breakdown charts
- [ ] Activity Log tab shows transaction history
**Header Credit Display:**
- [ ] Shows current credit balance
- [ ] Updates after AI operations
---
## Part 9: Error Messages (User-Friendly)
### Before (Technical)
```
HTTP 402 - HardLimitExceededError: max_keywords limit reached
```
### After (User-Friendly)
```
┌─────────────────────────────────────────────────────────┐
│ ⚠️ Keyword Limit Reached │
├─────────────────────────────────────────────────────────┤
│ │
│ You've reached your keyword limit. │
│ │
│ Current: 1,000 keywords │
│ Your plan allows: 1,000 keywords │
│ │
│ To add more keywords: │
│ • Delete unused keywords │
│ • Upgrade your plan │
│ │
│ [Manage Keywords] [Upgrade Plan] [Cancel] │
│ │
└─────────────────────────────────────────────────────────┘
```
---
## Part 10: Risk Mitigation
| Risk | Mitigation |
|------|------------|
| Migration breaks production | Test on staging with prod data clone first |
| Users lose tracked usage | Keep CreditUsageLog (detailed tracking continues) |
| Ahrefs costs spike | Monthly limit enforced server-side |
| Credit confusion | Clear documentation + help tooltips |
| Rollback needed | Keep migration reversible (add back fields) |
---
## Appendix A: Files to Modify
### Backend Files
| File | Changes |
|------|---------|
| `backend/igny8_core/auth/models.py` | Remove 11 fields, add 2 fields |
| `backend/igny8_core/business/billing/services/limit_service.py` | Simplify mappings |
| `backend/igny8_core/business/billing/serializers.py` | Update serializers |
| `backend/igny8_core/modules/billing/views.py` | Update usage summary |
| `backend/igny8_core/admin/` | Update admin panels |
| `backend/migrations/` | New migration file |
### Frontend Files
| File | Changes |
|------|---------|
| `frontend/src/pages/account/PlansAndBillingPage.tsx` | Simplify (remove usage) |
| `frontend/src/pages/account/UsageAnalyticsPage.tsx` | Add new tabs |
| `frontend/src/services/billing.api.ts` | Update interfaces |
| `frontend/src/components/billing/UsageLimitsPanel.tsx` | Show 4 limits only |
### Documentation Files
| File | Changes |
|------|---------|
| `docs/10-MODULES/BILLING.md` | Update limits documentation |
| `docs/40-WORKFLOWS/CREDIT-SYSTEM.md` | Update credit flow docs |
---
## Conclusion
The credit system architecture is **fundamentally correct**:
- `Plan.included_credits` defines monthly allocation
- `Account.credits` tracks real-time balance
- Credits are added on subscription renewal/payment approval
- Credits are deducted on each AI operation
**What's broken:**
- Too many unused limits causing user confusion
- Duplicate data displayed across pages
- Monthly limits (content_words, images, etc.) that duplicate what credits already control
**The fix:**
- Simplify to 4 hard limits + credits
- Clear page separation (financial vs consumption)
- Better UX with multi-dimensional credit insights
---
**Document Version:** 1.0
**Last Updated:** January 5, 2026
**Verified By:** Codebase review of backend and frontend
##############################################
## Organized Implementation Changes Plan
### 1. **Credit Consumption Widget (Rename & Enhance)**
**Current:** "Where Credits Go" with just a pie chart
**New:** "Credit Consumption" with pie chart + detailed table
| Operation | Credits Used | Items Created |
|-----------|-------------|---------------|
| Clustering | 150 | 12 clusters |
| Ideas | 200 | 45 ideas |
| Content | 1,200 | 24 articles |
| Image Prompts | 50 | 30 prompts |
| Images (Basic) | 100 | 100 images |
| Images (Quality) | 250 | 50 images |
| Images (Premium) | 450 | 30 images |
- Pie chart shows credits consumed per operation
- Table shows both **credits** AND **output count**
- Learn from Planner/Writer footer workflow completion widgets
---
### 2. **New Usage Logs Page** (`/account/usage/logs`)
**Purpose:** Detailed, filterable, paginated log of all AI operations
**Layout:** Same as Planner/Writer table pages (consistent template)
**Table Columns:**
| Date | Operation | Details | Credits | Cost (USD) |
|------|-----------|---------|-------|--------|---------|------------|
| Jan 5, 2:30pm | Content Writing | "SEO Guide for..." | 35 | $0.042 |
| Jan 5, 2:15pm | Image Generation | Premium quality | 15 | $0.18 |
**Features:**
- Filters: Operation type, date range, site
- Pagination
- USD cost calculated from token pricing (from AIModelConfig)
- Link to related content where applicable
- Export option
---
### 3. **Usage Dashboard - Multi-Dimensional Widgets**
**Remove:**
- ❌ "Operations" summary card (single metrics, not useful)
- ❌ "Recent Activity" card (move to Usage Logs page)
**Add/Enhance:**
- ✅ **Credit Consumption** (pie + table as described above)
- ✅ **Usage Trend** - Line chart showing daily/weekly credit usage
- ✅ **Credits by Site** - If multiple sites, show distribution
- ✅ **Image Quality Breakdown** - Basic vs Quality vs Premium usage
- ✅ **Top Operations** - Which operations consume most credits
- ✅ **Quick link** to Usage Logs page for detailed view
---
### 4. **Data Sources Needed**
From backend, I'll need to check:
- `CreditUsageLog` - Has operation_type, credits_used, model_used, tokens_in, tokens_out
- `AIModelConfig` - Has cost_per_1k_input, cost_per_1k_output for USD calculation
- Aggregations for: clusters created, ideas generated, articles written, images by tier
---
### Summary of Deliverables
| Item | Type | Description |
|------|------|-------------|
| 1 | Widget Enhancement | "Credit Consumption" - pie chart + table with credits & output counts |
| 2 | New Page | `/account/usage/logs` - Filterable, paginated AI operation logs with USD costs |
| 3 | Dashboard Update | Remove weak widgets, add multi-dimensional data-rich charts |
| 4 | Sidebar | Add "Usage Logs" as sub-item under Usage Dashboard |
---
**Does this organization look correct?** Should I proceed with implementation, or would you like to adjust any part of this plan?

274
docs/plans/implemented/IMPLEMENTATION-SUMMARY.md Normal file
View File

@@ -0,0 +1,274 @@
# 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:**
```python
max_ahrefs_queries = models.IntegerField(default=50)
```
**Account Model:**
```python
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:**
```python
# 1. Check credits
CreditService.check_credits(account, estimated_credits)
# 2. Execute
result = ai_service.execute()
# 3. Deduct
CreditService.deduct_credits_for_operation(...)
```
**Keyword Creation:**
```python
# Check limit
LimitService.check_hard_limit(account, 'keywords', count)
# Then create
Keywords.objects.bulk_create([...])
```
**Automation Runs:**
```python
# 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.

356
docs/plans/implemented/SYSTEM-ARCHITECTURE-DIAGRAM.md Normal file
View File

@@ -0,0 +1,356 @@
# 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.