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

Phase 3 - credts, usage, plans app pages #Migrations

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2026-01-06 21:28:13 +00:00
parent cb8e747387
commit 9ca048fb9d
37 changed files with 9328 additions and 1149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

529
docs/40-WORKFLOWS/CREDIT-SYSTEM.md
View File

@@ -1,169 +1,164 @@
# Usage & Content System
# Credit System
**Last Verified:** December 25, 2025
**Last Verified:** January 5, 2026
**Status:** ✅ Simplified (v1.5.0)
---
## Overview
IGNY8 uses a content-based allowance system. Users see "Content Pieces" while the backend tracks detailed credit consumption for internal cost monitoring.
**User View:** `47/50 Content Pieces Remaining`
**Backend Tracks:** Idea credits, content credits, image credits (for cost analysis)
IGNY8 uses a unified credit system where all AI operations consume credits from a single balance. Plan limits are simplified to 4 hard/monthly limits only.
---
## How It Works
### User-Facing (Simple)
| What Users See | Description |
|----------------|-------------|
| **Content Pieces** | Monthly allowance of pages/articles |
| **X/Y Remaining** | Used vs total for the month |
| **Upgrade Plan** | Get more content pieces |
### Backend (Detailed - Internal Only)
| Credit Type | Used For | Tracked For |
|-------------|----------|-------------|
| Idea Credits | Clustering, idea generation | Cost analysis |
| Content Credits | Article generation | Usage limits |
| Image Credits | Image generation | Cost analysis |
| Optimization Credits | SEO optimization (future) | Cost analysis |
---
## Plan Allowances
| Plan | Content Pieces/Month | Sites | Users |
|------|---------------------|-------|-------|
| Starter | 50 | 2 | 2 |
| Growth | 200 | 5 | 3 |
| Scale | 500 | Unlimited | 5 |
**Included with every content piece:**
- AI keyword clustering
- AI idea generation
- AI content writing (1000-2000 words)
- 3 images (1 featured + 2 in-article)
- Internal linking
- SEO optimization
- WordPress publishing
---
## Backend Soft Limits (Hidden from Users)
To prevent abuse, the backend enforces hidden limits:
| Limit | Starter | Growth | Scale |
|-------|---------|--------|-------|
| Keyword imports/mo | 500 | 2,000 | 5,000 |
| Clustering operations | 100 | 400 | 1,000 |
| Idea generations | 150 | 600 | 1,500 |
| Images generated | 200 | 800 | 2,000 |
If users hit these limits, they see: "You've reached your preparation limit for this month."
---
## Content Deduction Flow
## Credit Flow (Verified Architecture)
```
┌─────────────────────────────────────────────────────────────────┐
│ CONTENT CREATION FLOW │
│ CREDIT FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ User clicks Check Generate │
│ "Generate" ──────► Allowance ──────► Content │
│ │ │ │
│ │ Limit │ │
│ │ Reached ▼ │
│ ▼ Deduct 1 │
│ Show Upgrade Content │
│ Modal Piece │
│ 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` - When manual payment is approved
2. `payment_service.py` - When credit package purchased
3. `credit_service.py` - Generic `add_credits()` method
---
## Operations & Credit Costs
## Simplified Limits (v1.5.0)
### Planner Operations
### Hard Limits (Never Reset)
| Operation | Credits | Type |
|-----------|---------|------|
| Add keyword | 0 | Free |
| Auto-cluster keywords | 1 | Idea |
| Generate content ideas | 1 per idea | Idea |
| Limit | Plan Field | Account Field | Description |
|-------|------------|---------------|-------------|
| Sites | `max_sites` | (count of Site objects) | Maximum sites per account |
| Users | `max_users` | (count of User objects) | Maximum team members |
| Keywords | `max_keywords` | (count of Keyword objects) | Total keywords allowed |
### Writer Operations
### Monthly Limits (Reset on Billing Cycle)
| Operation | Credits | Type |
|-----------|---------|------|
| Create task | 0 | Free |
| Generate content | 1 | Content |
| Regenerate content | 1 | Content |
| Generate images | 1 per image | Image |
| Regenerate image | 1 | Image |
| Edit content | 0 | Free |
| Limit | Plan Field | Account Field | Description |
|-------|------------|---------------|-------------|
| Ahrefs Queries | `max_ahrefs_queries` | `usage_ahrefs_queries` | Live Ahrefs API queries per month |
### Automation Operations
### Removed Limits (Now Credit-Based)
| Operation | Credits | Type |
|-----------|---------|------|
| Run automation | Sum of operations | Mixed |
| Pause/resume | 0 | Free |
The following limits were removed in v1.5.0 - credits handle these:
- ~~max_clusters~~ → Credits
- ~~max_content_ideas~~ → Credits
- ~~max_content_words~~ → Credits
- ~~max_images_basic~~ → Credits
- ~~max_images_premium~~ → Credits
- ~~max_image_prompts~~ → Credits
### Publisher Operations
---
| Operation | Credits | Type |
|-----------|---------|------|
| Publish to WordPress | 0 | Free |
| Sync from WordPress | 0 | Free |
## Plan Tiers
### Optimizer Operations (Future)
| Plan | Credits/Month | Sites | Users | Keywords | Ahrefs Queries |
|------|---------------|-------|-------|----------|----------------|
| Free | 500 | 1 | 1 | 100 | 0 |
| Starter | 5,000 | 3 | 2 | 500 | 50 |
| Growth | 15,000 | 10 | 5 | 2,000 | 200 |
| Scale | 50,000 | Unlimited | 10 | 10,000 | 500 |
| Operation | Credits | Type |
|-----------|---------|------|
| Optimize content | 1 | Optimization |
| Batch optimize | 1 per item | Optimization |
---
## Credit Operations
### Token-Based Operations (Text AI)
Credits calculated from actual token usage:
- `credits = ceil(total_tokens / tokens_per_credit)`
- `tokens_per_credit` defined per model in `AIModelConfig`
| Operation | Model Example | tokens_per_credit |
|-----------|---------------|-------------------|
| Keyword Clustering | gpt-4o-mini | 10,000 |
| Idea Generation | gpt-4o-mini | 10,000 |
| Content Generation | gpt-4o | 1,000 |
| Content Optimization | gpt-4o-mini | 10,000 |
### Fixed-Cost Operations (Image AI)
Credits per image based on quality tier:
| Quality Tier | Model Example | Credits/Image |
|--------------|---------------|---------------|
| Basic | runware:97@1 | 1 |
| Quality | dall-e-3 | 5 |
| Premium | google:4@2 | 15 |
### Free Operations
| Operation | Cost |
|-----------|------|
| Add keyword (manual) | 0 |
| Create content task | 0 |
| Edit content | 0 |
| Publish to WordPress | 0 |
| Sync from WordPress | 0 |
---
## Database Models
### CreditBalance
### Account (Credit Balance)
```python
class CreditBalance(models.Model):
account = models.ForeignKey(Account)
site = models.ForeignKey(Site, null=True)
idea_credits = models.IntegerField(default=0)
content_credits = models.IntegerField(default=0)
image_credits = models.IntegerField(default=0)
optimization_credits = models.IntegerField(default=0)
period_start = models.DateField()
period_end = models.DateField()
class Account(models.Model):
credits = models.IntegerField(default=0) # Current balance
usage_ahrefs_queries = models.IntegerField(default=0) # Monthly Ahrefs usage
```
### CreditUsage
### Plan (Allocations)
```python
class CreditUsage(models.Model):
class Plan(models.Model):
included_credits = models.IntegerField(default=0) # Monthly allocation
max_sites = models.IntegerField(default=1)
max_users = models.IntegerField(default=1)
max_keywords = models.IntegerField(default=100)
max_ahrefs_queries = models.IntegerField(default=0) # Monthly Ahrefs limit
```
### CreditTransaction (Ledger)
```python
class CreditTransaction(models.Model):
account = models.ForeignKey(Account)
site = models.ForeignKey(Site, null=True)
user = models.ForeignKey(User)
credit_type = models.CharField() # idea/content/image/optimization
amount = models.IntegerField()
operation = models.CharField() # generate_content, etc.
created_at = models.DateTimeField(auto_now_add=True)
transaction_type = models.CharField() # purchase/subscription/refund/deduction
amount = models.DecimalField() # Positive (add) or negative (deduct)
balance_after = models.DecimalField()
description = models.CharField()
created_at = models.DateTimeField()
```
### CreditUsageLog (Analytics)
```python
class CreditUsageLog(models.Model):
account = models.ForeignKey(Account)
operation_type = models.CharField() # clustering/content_generation/image_generation
credits_used = models.DecimalField()
model_used = models.CharField()
tokens_input = models.IntegerField()
tokens_output = models.IntegerField()
created_at = models.DateTimeField()
```
---
@@ -172,26 +167,58 @@ class CreditUsage(models.Model):
### CreditService
Location: `backend/igny8_core/business/billing/services.py`
Location: `backend/igny8_core/business/billing/services/credit_service.py`
**Key Methods:**
```python
class CreditService:
def check_balance(account, site, credit_type, amount) -> bool:
"""Check if sufficient credits available"""
@staticmethod
def check_credits(account, required_credits):
"""Check if sufficient credits available, raises InsufficientCreditsError if not"""
def deduct_credits(account, site, user, credit_type, amount, operation) -> bool:
"""Deduct credits and log usage"""
@staticmethod
def deduct_credits_for_operation(account, operation_type, model, tokens_in, tokens_out, metadata=None):
"""Deduct credits and log usage after AI operation"""
def get_balance(account, site) -> CreditBalance:
"""Get current balance"""
@staticmethod
def add_credits(account, amount, transaction_type, description):
"""Add credits (admin/purchase/subscription)"""
def reset_monthly_credits(account) -> None:
"""Reset credits at period start"""
@staticmethod
def calculate_credits_from_tokens(operation_type, tokens_in, tokens_out, model=None):
"""Calculate credits based on token usage and model"""
```
### LimitService
Location: `backend/igny8_core/business/billing/services/limit_service.py`
**Key Methods:**
```python
class LimitService:
HARD_LIMIT_MAPPINGS = {
'sites': {...},
'users': {...},
'keywords': {...},
}
MONTHLY_LIMIT_MAPPINGS = {
'ahrefs_queries': {...},
}
@classmethod
def check_hard_limit(cls, account, limit_name, additional_count=1):
"""Check if adding items would exceed hard limit"""
def add_credits(account, credit_type, amount, reason) -> None:
"""Add credits (admin/purchase)"""
@classmethod
def check_monthly_limit(cls, account, limit_name, additional_count=1):
"""Check if operation would exceed monthly limit"""
@classmethod
def increment_monthly_usage(cls, account, limit_name, count=1):
"""Increment monthly usage counter"""
```
### Usage in AI Operations
@@ -199,26 +226,23 @@ class CreditService:
```python
# In content generation service
def generate_content(task, user):
# 1. Check balance
if not credit_service.check_balance(
account=task.site.account,
site=task.site,
credit_type='content',
amount=1
):
raise InsufficientCreditsError()
account = task.site.account
# 1. Pre-check credits (estimated)
estimated_credits = 50 # Estimate for content generation
CreditService.check_credits(account, estimated_credits)
# 2. Execute AI function
content = ai_engine.generate_content(task)
content, usage = ai_engine.generate_content(task)
# 3. Deduct credits
credit_service.deduct_credits(
account=task.site.account,
site=task.site,
user=user,
credit_type='content',
amount=1,
operation='generate_content'
# 3. Deduct actual credits based on token usage
CreditService.deduct_credits_for_operation(
account=account,
operation_type='content_generation',
model=usage.model,
tokens_in=usage.input_tokens,
tokens_out=usage.output_tokens,
metadata={'content_id': content.id}
)
return content
@@ -228,19 +252,14 @@ def generate_content(task, user):
## API Responses
### Successful Deduction
### Successful Operation
```json
{
"success": true,
"data": { ... },
"credits_used": {
"type": "content",
"amount": 1
},
"balance": {
"content_credits": 49
}
"credits_used": 15,
"balance": 9985
}
```
@@ -251,10 +270,25 @@ HTTP 402 Payment Required
{
"success": false,
"error": "Insufficient content credits",
"error": "Insufficient credits",
"code": "INSUFFICIENT_CREDITS",
"required": 1,
"available": 0
"required": 50,
"available": 25
}
```
### Limit Exceeded
```json
HTTP 402 Payment Required
{
"success": false,
"error": "Keyword limit reached",
"code": "HARD_LIMIT_EXCEEDED",
"limit": "keywords",
"current": 500,
"max": 500
}
```
@@ -262,113 +296,125 @@ HTTP 402 Payment Required
## Frontend Handling
### Balance Display
### Credit Balance Display
- Header shows credit balances
- Header shows current credit balance
- Updates after each operation
- Warning at low balance (< 10%)
### Error Handling
### Pre-Operation Check
```typescript
// In writer store
async generateContent(taskId: string) {
try {
const response = await api.generateContent(taskId);
// Update billing store
billingStore.fetchBalance();
return response;
} catch (error) {
if (error.code === 'INSUFFICIENT_CREDITS') {
// Show upgrade modal
uiStore.showUpgradeModal();
import { checkCreditsBeforeOperation } from '@/utils/creditCheck';
import { useInsufficientCreditsModal } from '@/components/billing/InsufficientCreditsModal';
function ContentGenerator() {
const { showModal } = useInsufficientCreditsModal();
const handleGenerate = async () => {
// Check credits before operation
const check = await checkCreditsBeforeOperation(50); // estimated cost
if (!check.hasEnoughCredits) {
showModal({
requiredCredits: check.requiredCredits,
availableCredits: check.availableCredits,
});
return;
}
throw error;
}
// Proceed with generation
await generateContent();
};
}
```
---
## Usage Tracking
## API Endpoints
### Usage Summary Endpoint
### Credit Balance
```
GET /api/v1/billing/usage/summary/?period=month
GET /api/v1/billing/balance/
```
Response:
```json
{
"period": "2025-01",
"usage": {
"idea_credits": 45,
"content_credits": 23,
"image_credits": 67,
"optimization_credits": 0
},
"by_operation": {
"auto_cluster": 12,
"generate_ideas": 33,
"generate_content": 23,
"generate_images": 67
}
"credits": 9500,
"plan_credits_per_month": 10000,
"credits_used_this_month": 500,
"credits_remaining": 9500
}
```
---
## Automation Credit Estimation
Before running automation:
### Usage Limits
```
GET /api/v1/automation/estimate/?site_id=...
GET /api/v1/billing/usage/limits/
```
Response:
```json
{
"estimated_credits": {
"idea_credits": 25,
"content_credits": 10,
"image_credits": 30
"limits": {
"sites": { "current": 2, "limit": 5, "type": "hard" },
"users": { "current": 2, "limit": 3, "type": "hard" },
"keywords": { "current": 847, "limit": 1000, "type": "hard" },
"ahrefs_queries": { "current": 23, "limit": 50, "type": "monthly" }
},
"stages": {
"clustering": 5,
"ideas": 20,
"content": 10,
"images": 30
},
"has_sufficient_credits": true
"days_until_reset": 18
}
```
### Usage Analytics
```
GET /api/v1/account/usage/analytics/?days=30
```
Response:
```json
{
"period_days": 30,
"start_date": "2025-12-06",
"end_date": "2026-01-05",
"current_balance": 9500,
"total_usage": 500,
"total_purchases": 0,
"usage_by_type": [
{ "transaction_type": "content_generation", "total": -350, "count": 15 },
{ "transaction_type": "image_generation", "total": -100, "count": 20 },
{ "transaction_type": "clustering", "total": -50, "count": 10 }
],
"daily_usage": [
{ "date": "2026-01-05", "usage": 25, "purchases": 0, "net": -25 }
]
}
```
---
## Credit Reset
## Credit Allocation
Credits reset monthly based on billing cycle:
Credits are added to `Account.credits` when:
1. **Monthly Reset Job** runs at period end
2. **Unused credits** do not roll over
3. **Purchased credits** may have different expiry
1. **Subscription Renewal** - `Plan.included_credits` added monthly
2. **Payment Approval** - Manual payments approved by admin
3. **Credit Purchase** - Credit packages bought by user
4. **Admin Adjustment** - Manual credit grants/adjustments
### Celery Task
### Monthly Reset
Monthly limits (Ahrefs queries) reset on billing cycle:
```python
@celery.task
def reset_monthly_credits():
"""
Run daily, resets credits for accounts
whose period_end is today
"""
today = date.today()
balances = CreditBalance.objects.filter(period_end=today)
for balance in balances:
credit_service.reset_monthly_credits(balance.account)
# In Account model
def reset_monthly_usage(self):
"""Reset monthly usage counters (called on billing cycle renewal)"""
self.usage_ahrefs_queries = 0
self.save(update_fields=['usage_ahrefs_queries'])
```
---
@@ -380,20 +426,29 @@ def reset_monthly_credits():
Via Django Admin or API:
```python
from igny8_core.business.billing.services.credit_service import CreditService
# Add credits
credit_service.add_credits(
CreditService.add_credits(
account=account,
credit_type='content',
amount=100,
reason='Customer support adjustment'
amount=1000,
transaction_type='adjustment',
description='Customer support adjustment'
)
```
### Usage Audit
All credit changes logged in `CreditUsage` with:
All credit changes logged in `CreditTransaction` with:
- Timestamp
- User who triggered
- Transaction type
- Amount (positive or negative)
- Balance after transaction
- Description
All AI operations logged in `CreditUsageLog` with:
- Operation type
- Amount deducted
- Related object ID
- Credits used
- Model used
- Token counts
- Related object metadata