400 lines
9.2 KiB
Markdown
400 lines
9.2 KiB
Markdown
# Usage & Content System
|
|
|
|
**Last Verified:** December 25, 2025
|
|
|
|
---
|
|
|
|
## 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)
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CONTENT CREATION FLOW │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ User clicks Check Generate │
|
|
│ "Generate" ──────► Allowance ──────► Content │
|
|
│ │ │ │
|
|
│ │ Limit │ │
|
|
│ │ Reached ▼ │
|
|
│ ▼ Deduct 1 │
|
|
│ Show Upgrade Content │
|
|
│ Modal Piece │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Operations & Credit Costs
|
|
|
|
### Planner Operations
|
|
|
|
| Operation | Credits | Type |
|
|
|-----------|---------|------|
|
|
| Add keyword | 0 | Free |
|
|
| Auto-cluster keywords | 1 | Idea |
|
|
| Generate content ideas | 1 per idea | Idea |
|
|
|
|
### Writer Operations
|
|
|
|
| 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 |
|
|
|
|
### Automation Operations
|
|
|
|
| Operation | Credits | Type |
|
|
|-----------|---------|------|
|
|
| Run automation | Sum of operations | Mixed |
|
|
| Pause/resume | 0 | Free |
|
|
|
|
### Publisher Operations
|
|
|
|
| Operation | Credits | Type |
|
|
|-----------|---------|------|
|
|
| Publish to WordPress | 0 | Free |
|
|
| Sync from WordPress | 0 | Free |
|
|
|
|
### Optimizer Operations (Future)
|
|
|
|
| Operation | Credits | Type |
|
|
|-----------|---------|------|
|
|
| Optimize content | 1 | Optimization |
|
|
| Batch optimize | 1 per item | Optimization |
|
|
|
|
---
|
|
|
|
## Database Models
|
|
|
|
### CreditBalance
|
|
|
|
```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()
|
|
```
|
|
|
|
### CreditUsage
|
|
|
|
```python
|
|
class CreditUsage(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)
|
|
```
|
|
|
|
---
|
|
|
|
## Business Logic
|
|
|
|
### CreditService
|
|
|
|
Location: `backend/igny8_core/business/billing/services.py`
|
|
|
|
**Key Methods:**
|
|
|
|
```python
|
|
class CreditService:
|
|
def check_balance(account, site, credit_type, amount) -> bool:
|
|
"""Check if sufficient credits available"""
|
|
|
|
def deduct_credits(account, site, user, credit_type, amount, operation) -> bool:
|
|
"""Deduct credits and log usage"""
|
|
|
|
def get_balance(account, site) -> CreditBalance:
|
|
"""Get current balance"""
|
|
|
|
def reset_monthly_credits(account) -> None:
|
|
"""Reset credits at period start"""
|
|
|
|
def add_credits(account, credit_type, amount, reason) -> None:
|
|
"""Add credits (admin/purchase)"""
|
|
```
|
|
|
|
### Usage in AI Operations
|
|
|
|
```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()
|
|
|
|
# 2. Execute AI function
|
|
content = 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'
|
|
)
|
|
|
|
return content
|
|
```
|
|
|
|
---
|
|
|
|
## API Responses
|
|
|
|
### Successful Deduction
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": { ... },
|
|
"credits_used": {
|
|
"type": "content",
|
|
"amount": 1
|
|
},
|
|
"balance": {
|
|
"content_credits": 49
|
|
}
|
|
}
|
|
```
|
|
|
|
### Insufficient Credits
|
|
|
|
```json
|
|
HTTP 402 Payment Required
|
|
|
|
{
|
|
"success": false,
|
|
"error": "Insufficient content credits",
|
|
"code": "INSUFFICIENT_CREDITS",
|
|
"required": 1,
|
|
"available": 0
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Frontend Handling
|
|
|
|
### Balance Display
|
|
|
|
- Header shows credit balances
|
|
- Updates after each operation
|
|
- Warning at low balance (< 10%)
|
|
|
|
### Error Handling
|
|
|
|
```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();
|
|
}
|
|
throw error;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Usage Tracking
|
|
|
|
### Usage Summary Endpoint
|
|
|
|
```
|
|
GET /api/v1/billing/usage/summary/?period=month
|
|
```
|
|
|
|
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
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Automation Credit Estimation
|
|
|
|
Before running automation:
|
|
|
|
```
|
|
GET /api/v1/automation/estimate/?site_id=...
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"estimated_credits": {
|
|
"idea_credits": 25,
|
|
"content_credits": 10,
|
|
"image_credits": 30
|
|
},
|
|
"stages": {
|
|
"clustering": 5,
|
|
"ideas": 20,
|
|
"content": 10,
|
|
"images": 30
|
|
},
|
|
"has_sufficient_credits": true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Credit Reset
|
|
|
|
Credits reset monthly based on billing cycle:
|
|
|
|
1. **Monthly Reset Job** runs at period end
|
|
2. **Unused credits** do not roll over
|
|
3. **Purchased credits** may have different expiry
|
|
|
|
### Celery Task
|
|
|
|
```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)
|
|
```
|
|
|
|
---
|
|
|
|
## Admin Operations
|
|
|
|
### Manual Credit Adjustment
|
|
|
|
Via Django Admin or API:
|
|
|
|
```python
|
|
# Add credits
|
|
credit_service.add_credits(
|
|
account=account,
|
|
credit_type='content',
|
|
amount=100,
|
|
reason='Customer support adjustment'
|
|
)
|
|
```
|
|
|
|
### Usage Audit
|
|
|
|
All credit changes logged in `CreditUsage` with:
|
|
- Timestamp
|
|
- User who triggered
|
|
- Operation type
|
|
- Amount deducted
|
|
- Related object ID
|