# 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.