342 lines
11 KiB
Markdown
342 lines
11 KiB
Markdown
# Production Readiness Plan
|
|
|
|
**Created:** December 25, 2025
|
|
**Last Updated:** December 25, 2025
|
|
**Goal:** Ship to production with simplified UI while keeping backend unchanged
|
|
**Status:** ✅ CORE CHANGES COMPLETE
|
|
|
|
---
|
|
|
|
## Implementation Status
|
|
|
|
### ✅ Completed Changes
|
|
|
|
| File | Change | Status |
|
|
|------|--------|--------|
|
|
| `layout/AppLayout.tsx` | Header shows "Content: X/Y" | ✅ Done |
|
|
| `pages/Dashboard/Home.tsx` | Credit widget → "Content This Month" | ✅ Done |
|
|
| `pages/Help/Help.tsx` | FAQ updated | ✅ Done |
|
|
| `pages/Automation/AutomationPage.tsx` | Error messages updated | ✅ Done |
|
|
| `components/auth/SignUpForm*.tsx` | 3 files - removed credit text | ✅ Done |
|
|
| `pages/Settings/Plans.tsx` | Shows "Pages/Articles per month" | ✅ Done |
|
|
| `pages/account/PlansAndBillingPage.tsx` | Tabs simplified, Purchase Credits hidden | ✅ Done |
|
|
| `pages/Payment.tsx` | Updated pricing display | ✅ Done |
|
|
| `pages/Optimizer/Dashboard.tsx` | Removed credits card | ✅ Done |
|
|
| `pages/Settings/CreditsAndBilling.tsx` | Renamed to "Usage & Billing" | ✅ Done |
|
|
| `pages/Billing/Credits.tsx` | Renamed to "Content Usage" | ✅ Done |
|
|
| `components/billing/BillingBalancePanel.tsx` | "Usage Overview" | ✅ Done |
|
|
| `components/dashboard/CreditBalanceWidget.tsx` | "Content Usage" | ✅ Done |
|
|
| `components/dashboard/UsageChartWidget.tsx` | "Content Created" | ✅ Done |
|
|
| `components/ui/pricing-table/index.tsx` | "Content pieces/month" | ✅ Done |
|
|
| `marketing/pages/Pricing.tsx` | "Usage Dashboard" | ✅ Done |
|
|
| `docs/40-WORKFLOWS/CREDIT-SYSTEM.md` | Updated docs | ✅ Done |
|
|
|
|
### Hidden from Regular Users
|
|
|
|
| Feature | Status |
|
|
|---------|--------|
|
|
| Purchase Credits page | Hidden (commented out) |
|
|
| Credit Cost Breakdown | Hidden |
|
|
| Credit Packages grid | Hidden |
|
|
| Detailed credit analytics | Hidden |
|
|
|
|
---
|
|
|
|
## The Strategy: Abstraction Layer
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ WHAT CHANGES │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ BACKEND (NO CHANGES) FRONTEND (CHANGES) │
|
|
│ ────────────────────── ────────────────── │
|
|
│ • Credit deduction ✓ • Hide credit numbers ✅ │
|
|
│ • Usage tracking ✓ • Show "Content Pieces" ✅ │
|
|
│ • Plan limits ✓ • Simplify terminology ✅ │
|
|
│ • API responses ✓ • Remove purchase credits ✅ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Key Insight:** Backend tracks `content_credits`. User sees this as "Content Pieces".
|
|
No conversion needed - just rename the display.
|
|
|
|
---
|
|
|
|
## Phase 1: Core Abstraction (billingStore)
|
|
|
|
### File: `frontend/src/store/billingStore.ts`
|
|
|
|
Add computed properties that translate credits → content pieces:
|
|
|
|
```typescript
|
|
// Add to BillingState interface
|
|
interface BillingState {
|
|
// ... existing ...
|
|
|
|
// Computed for simple UI
|
|
getContentPiecesRemaining: () => number;
|
|
getContentPiecesUsed: () => number;
|
|
getContentPiecesTotal: () => number;
|
|
}
|
|
|
|
// In the store
|
|
getContentPiecesRemaining: () => {
|
|
const balance = get().balance;
|
|
// content_credits = content pieces (1:1 mapping)
|
|
return balance?.credits_remaining ?? 0;
|
|
},
|
|
|
|
getContentPiecesUsed: () => {
|
|
const balance = get().balance;
|
|
return balance?.credits_used_this_month ?? 0;
|
|
},
|
|
|
|
getContentPiecesTotal: () => {
|
|
const balance = get().balance;
|
|
return balance?.plan_credits_per_month ?? 0;
|
|
},
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 2: Header Metrics Update
|
|
|
|
### File: `frontend/src/layout/AppLayout.tsx`
|
|
|
|
**Current (line ~138):**
|
|
```typescript
|
|
{
|
|
label: 'Credits',
|
|
value: balance.credits.toLocaleString(),
|
|
// ...
|
|
}
|
|
```
|
|
|
|
**Change to:**
|
|
```typescript
|
|
{
|
|
label: 'Content',
|
|
value: `${balance.credits_remaining}/${balance.plan_credits_per_month}`,
|
|
tooltip: 'Content pieces remaining this month'
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 3: Pages to Update
|
|
|
|
### Priority 1: Remove/Hide These Pages
|
|
|
|
| Page | File | Action |
|
|
|------|------|--------|
|
|
| Purchase Credits | `pages/account/PurchaseCreditsPage.tsx` | Hide from nav, keep for admin |
|
|
| Credits Tab | `pages/Billing/Credits.tsx` | Remove tab from billing |
|
|
| Credits & Billing | `pages/Settings/CreditsAndBilling.tsx` | Rename to "Usage" |
|
|
|
|
### Priority 2: Update Text/Labels
|
|
|
|
| Page | File | Changes |
|
|
|------|------|---------|
|
|
| Dashboard | `pages/Dashboard/Home.tsx` | "Credits" → "Content Pieces" |
|
|
| Plans & Billing | `pages/account/PlansAndBillingPage.tsx` | Remove Credits tab, simplify |
|
|
| Usage Analytics | `pages/account/UsageAnalyticsPage.tsx` | "Credits" → "Content" |
|
|
| Automation | `pages/Automation/AutomationPage.tsx` | "credits" → "content pieces" |
|
|
| Help | `pages/Help/Help.tsx` | Update FAQ text |
|
|
|
|
### Priority 3: Marketing Pages
|
|
|
|
| Page | File | Changes |
|
|
|------|------|---------|
|
|
| Pricing | `marketing/pages/Pricing.tsx` | Already updated per session |
|
|
| Waitlist | `marketing/pages/Waitlist.tsx` | Update copy |
|
|
|
|
---
|
|
|
|
## Phase 4: Components to Update
|
|
|
|
### High Priority
|
|
|
|
| Component | File | Changes |
|
|
|-----------|------|---------|
|
|
| CreditBalanceWidget | `components/dashboard/CreditBalanceWidget.tsx` | Rename to ContentBalanceWidget |
|
|
| BillingBalancePanel | `components/billing/BillingBalancePanel.tsx` | Remove "Purchase Credits" link |
|
|
| BillingUsagePanel | `components/billing/BillingUsagePanel.tsx` | Simplify display |
|
|
| CurrentProcessingCard | `components/Automation/CurrentProcessingCard.tsx` | "Credits Used" → "Content Generated" |
|
|
| RunHistory | `components/Automation/RunHistory.tsx` | Same |
|
|
|
|
### Medium Priority (Can ship with these unchanged)
|
|
|
|
| Component | File | Notes |
|
|
|-----------|------|-------|
|
|
| CreditCostBreakdownPanel | `components/billing/CreditCostBreakdownPanel.tsx` | Admin only, keep |
|
|
| CreditCostsPanel | `components/billing/CreditCostsPanel.tsx` | Admin only, keep |
|
|
| UsageChartWidget | `components/dashboard/UsageChartWidget.tsx` | Keep for analytics |
|
|
|
|
---
|
|
|
|
## Phase 5: Routes to Update
|
|
|
|
### File: `frontend/src/App.tsx`
|
|
|
|
**Remove from user routes:**
|
|
```typescript
|
|
// Remove or hide:
|
|
<Route path="/account/purchase-credits" element={<PurchaseCreditsPage />} />
|
|
<Route path="/billing/credits" element={<Credits />} />
|
|
```
|
|
|
|
**Keep for admin access only** (add admin check)
|
|
|
|
---
|
|
|
|
## Phase 6: Terminology Mapping
|
|
|
|
Use this mapping consistently:
|
|
|
|
| OLD (Backend/Internal) | NEW (User-Facing) |
|
|
|------------------------|-------------------|
|
|
| credits | content pieces |
|
|
| credit balance | content remaining |
|
|
| credits used | content generated |
|
|
| plan_credits_per_month | monthly content limit |
|
|
| credits_remaining | content pieces left |
|
|
| insufficient credits | content limit reached |
|
|
| purchase credits | upgrade plan |
|
|
|
|
---
|
|
|
|
## Phase 7: Error Messages
|
|
|
|
### File: Create `frontend/src/utils/userFriendlyMessages.ts`
|
|
|
|
```typescript
|
|
export const USER_MESSAGES = {
|
|
INSUFFICIENT_CREDITS: "You've reached your content limit for this month. Upgrade your plan for more.",
|
|
CREDIT_DEDUCTED: "Content piece generated successfully",
|
|
LOW_BALANCE: "You're running low on content pieces this month",
|
|
|
|
// Operation-specific
|
|
CLUSTERING_SUCCESS: "Keywords organized into topics",
|
|
IDEAS_SUCCESS: "Content ideas generated",
|
|
CONTENT_SUCCESS: "Article draft created",
|
|
IMAGES_SUCCESS: "Images generated",
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Order
|
|
|
|
### Day 1: Core Changes (Ship Blocker)
|
|
|
|
1. [ ] Update `billingStore.ts` with computed properties
|
|
2. [ ] Update `AppLayout.tsx` header metric
|
|
3. [ ] Update `PlansAndBillingPage.tsx` - remove Credits tab
|
|
4. [ ] Hide Purchase Credits route (don't delete)
|
|
|
|
### Day 2: Dashboard & Key Pages
|
|
|
|
5. [ ] Update `Dashboard/Home.tsx` labels
|
|
6. [ ] Update `UsageAnalyticsPage.tsx` labels
|
|
7. [ ] Update `AutomationPage.tsx` labels
|
|
8. [ ] Update `Help.tsx` FAQ content
|
|
|
|
### Day 3: Components & Polish
|
|
|
|
9. [ ] Rename CreditBalanceWidget → ContentBalanceWidget
|
|
10. [ ] Update BillingBalancePanel
|
|
11. [ ] Update CurrentProcessingCard
|
|
12. [ ] Update RunHistory
|
|
|
|
### Day 4: Marketing & Final
|
|
|
|
13. [ ] Verify Pricing page is correct
|
|
14. [ ] Update Waitlist/Tour pages
|
|
15. [ ] Update SignUp form text
|
|
16. [ ] Final QA pass
|
|
|
|
---
|
|
|
|
## What NOT to Change
|
|
|
|
Keep these exactly as-is:
|
|
|
|
1. **Backend API endpoints** - All `/v1/billing/*` endpoints
|
|
2. **Database models** - CreditBalance, CreditUsage, etc.
|
|
3. **Credit deduction logic** - In business services
|
|
4. **Admin pages** - Keep full credit visibility for admins
|
|
5. **API responses** - Backend still returns `credits`, frontend translates
|
|
|
|
---
|
|
|
|
## Backend Soft Limits (Already Implemented)
|
|
|
|
Per the pricing session, backend should enforce:
|
|
|
|
| Limit | Starter | Growth | Scale |
|
|
|-------|---------|--------|-------|
|
|
| Content pieces/mo | 50 | 200 | 500 |
|
|
| Keyword imports/mo | 500 | 2,000 | 5,000 |
|
|
| Clustering ops/mo | 100 | 400 | 1,000 |
|
|
| Idea generations/mo | 150 | 600 | 1,500 |
|
|
|
|
**If not implemented:** These are hidden from user but prevent abuse. Add backend validation in:
|
|
- `backend/igny8_core/business/billing/services.py`
|
|
|
|
---
|
|
|
|
## Quick Wins (Can Do Now)
|
|
|
|
### 1. Header Metric (5 min)
|
|
|
|
In `AppLayout.tsx`, change:
|
|
```typescript
|
|
label: 'Credits',
|
|
```
|
|
to:
|
|
```typescript
|
|
label: 'Content',
|
|
```
|
|
|
|
### 2. Help FAQ (5 min)
|
|
|
|
In `Help.tsx`, update the credits question to:
|
|
```
|
|
question: "How does content usage work?"
|
|
answer: "Each plan includes a monthly content allowance. Creating articles, generating ideas, and producing images all count toward your monthly limit. View your usage in Settings > Usage."
|
|
```
|
|
|
|
### 3. Hide Purchase Credits Link (5 min)
|
|
|
|
In `BillingBalancePanel.tsx`, remove or conditionally hide:
|
|
```typescript
|
|
<Link to="/account/purchase-credits">Purchase Credits</Link>
|
|
```
|
|
|
|
---
|
|
|
|
## Testing Checklist
|
|
|
|
Before production:
|
|
|
|
- [ ] User can see "47/50 Content" in header (not "835 Credits")
|
|
- [ ] Plans page shows content pieces, not credits
|
|
- [ ] No "Purchase Credits" visible to regular users
|
|
- [ ] Automation shows "Content Generated: 5" not "Credits Used: 5"
|
|
- [ ] Error on limit shows "Content limit reached" not "Insufficient credits"
|
|
- [ ] Dashboard shows simple progress bar with content count
|
|
- [ ] Help/FAQ explains content pieces, not credits
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
**Total effort:** ~2-3 days of frontend work
|
|
**Backend changes:** Zero
|
|
**Risk:** Low (display-only changes)
|
|
**Rollback:** Easy (revert frontend only)
|
|
|
|
The system still tracks everything internally with credits. Users just see a simpler "content pieces" model that maps 1:1 to content credits.
|