feat(billing): Build Scalable Credit Economy, Community Wallet, Usage Billing & Cost-Control Infrastructure

<html><head></head><body>

<img width="1084" height="1600" alt="Image" src="https://github.com/user-attachments/assets/9124130a-4aa5-4529-bef8-416e0cf54b67" />

<hr><h1>📌 Objective</h1><p>Design and implement a <strong>production-grade internal credit economy system</strong> for <a href="https://commdesk.example.com/?utm_source=chatgpt.com">CommDesk</a> that enables:</p><ul><li><p>Pay-as-you-go billing</p></li><li><p>Community wallet management</p></li><li><p>Real-time usage deduction</p></li><li><p>Credit-based infrastructure abstraction</p></li><li><p>Payout handling</p></li><li><p>Revenue optimization</p></li><li><p>AI/API future-proof monetization</p></li><li><p>Enterprise-grade cost control</p></li></ul><p>This system should support scaling from:</p><pre><code class="language-txt">small communities → enterprise organizations → AI-powered SaaS ecosystem
</code></pre><hr><h1>🎯 Product Vision</h1><p>Instead of charging users directly in rupees for every feature:</p><pre><code class="language-txt">Users purchase Credits → Credits are consumed by platform usage
</code></pre><p>This creates:</p><ul><li><p>Better UX</p></li><li><p>Easier pricing management</p></li><li><p>Infrastructure cost abstraction</p></li><li><p>Easier AI monetization</p></li><li><p>Better profit margins</p></li><li><p>Cleaner analytics</p></li><li><p>Enterprise scalability</p></li></ul><hr><h1>💰 Official Credit Conversion System</h1><h2>Final Conversion Model</h2><pre><code class="language-txt">₹10 = 100 Credits
</code></pre><hr><h1>❌ Avoid</h1><pre><code class="language-txt">₹10 = 10 Credits
</code></pre><p>Reason:</p><ul><li><p>Hard to micro-price features</p></li><li><p>Decimal-heavy pricing</p></li><li><p>Poor UX psychology</p></li><li><p>Difficult AI/API pricing</p></li><li><p>Weak future scaling</p></li></ul><hr><h1>✅ Advantages of 100 Credits System</h1>
Benefit | Explanation
-- | --
Micro Billing | Fine-grained pricing
Better UX | Users feel larger value
Cleaner UI | Avoid decimals
Easier Pricing | Flexible feature costing
AI-Ready | AI token pricing becomes easier
Revenue Safe | Better margin control
Scalable | Supports enterprise billing

<hr><h1>3️⃣ Suspicious Activity Detection</h1><p>Flag:</p><ul><li><p>Rapid burn patterns</p></li><li><p>Payment fraud</p></li><li><p>Multi-account abuse</p></li><li><p>Infinite retries</p></li></ul><hr><h1>4️⃣ Graceful Credit Exhaustion</h1><p>When credits run out:</p><ul><li><p>Pause premium features</p></li><li><p>Keep core community accessible</p></li><li><p>Show low balance modal</p></li></ul><hr><h1>🔐 Security Requirements</h1><hr><h1>Billing Security</h1><ul><li><p>Double-spend prevention</p></li><li><p>Atomic deductions</p></li><li><p>Idempotency keys</p></li><li><p>Webhook signature verification</p></li><li><p>Fraud scoring</p></li><li><p>Replay attack prevention</p></li></ul><hr><h1>Database Safety</h1><ul><li><p>Transactions mandatory</p></li><li><p>Optimistic locking</p></li><li><p>Ledger consistency validation</p></li><li><p>Immutable transaction records</p></li></ul><hr><h1>🏗️ Backend APIs</h1><hr><h1>Wallet APIs</h1><pre><code class="language-http">GET    /wallet
GET    /wallet/transactions
POST   /wallet/add-funds
POST   /wallet/consume
POST   /wallet/refund
</code></pre><hr><h1>Analytics APIs</h1><pre><code class="language-http">GET /usage/summary
GET /usage/breakdown
GET /usage/forecast
</code></pre><hr><h1>Auto Recharge APIs</h1><pre><code class="language-http">POST /wallet/auto-recharge/enable
POST /wallet/auto-recharge/disable
</code></pre><hr><h1>🧪 Testing Requirements</h1><hr><h1>Unit Tests</h1><ul><li><p>Credit calculations</p></li><li><p>Wallet deductions</p></li><li><p>Refund logic</p></li><li><p>Bonus credit logic</p></li><li><p>Usage forecasting</p></li></ul><hr><h1>Integration Tests</h1><ul><li><p>Payment → Wallet sync</p></li><li><p>Deduction engine</p></li><li><p>Retry handling</p></li><li><p>Webhook validation</p></li></ul><hr><h1>E2E Tests</h1><p>Using:</p><ul><li><p>Playwright</p></li><li><p>Cypress</p></li></ul><p>Scenarios:</p><ul><li><p>Add funds</p></li><li><p>Failed payment</p></li><li><p>Retry payment</p></li><li><p>AI consumption</p></li><li><p>Low balance alert</p></li><li><p>Auto recharge</p></li></ul><hr><h1>📱 UI/UX Requirements</h1><hr><h1>Design Inspiration</h1><ul><li><p><a href="https://stripe.com/?utm_source=chatgpt.com">Stripe Billing</a></p></li><li><p><a href="https://aws.amazon.com/billing/?utm_source=chatgpt.com">AWS Billing Console</a></p></li><li><p><a href="https://vercel.com/?utm_source=chatgpt.com">Vercel Dashboard</a></p></li><li><p><a href="https://linear.app/?utm_source=chatgpt.com">Linear</a></p></li></ul><hr><h1>Requirements</h1><ul><li><p>Dark mode</p></li><li><p>Fully responsive</p></li><li><p>Skeleton loading</p></li><li><p>Smooth animations</p></li><li><p>Real-time updates</p></li><li><p>Optimistic UI</p></li><li><p>Mobile-first modal system</p></li></ul><hr><h1>⚡ Performance Requirements</h1><ul><li><p>Cached analytics</p></li><li><p>Lazy loading</p></li><li><p>Virtualized transaction tables</p></li><li><p>Batched ledger writes</p></li><li><p>SSE/WebSocket live updates</p></li></ul><hr><h1>📈 Business Goal</h1><p>Target infrastructure cost ratio:</p><pre><code class="language-txt">25–45% infra cost
35–50% gross margin
</code></pre><p>System should remain profitable even during:</p><ul><li><p>AI-heavy workloads</p></li><li><p>High webhook usage</p></li><li><p>Large communities</p></li><li><p>Export-heavy operations</p></li></ul><hr><h1>✅ Acceptance Criteria</h1><ul><li><p>Fully working wallet system</p></li><li><p>Centralized credit engine</p></li><li><p>Immutable billing ledger</p></li><li><p>Real-time analytics</p></li><li><p>Add funds flow working</p></li><li><p>Auto recharge implemented</p></li><li><p>Abuse prevention active</p></li><li><p>Production-grade security</p></li><li><p>Full test coverage</p></li><li><p>Mobile responsive UI</p></li><li><p>Enterprise-ready scalability</p></li></ul><hr><h1>🏷️ Labels</h1><pre><code class="language-txt">feature
billing
wallet
payments
credits
analytics
enterprise
high-priority
backend
frontend
security
</code></pre><hr><h1>📌 Priority</h1><pre><code class="language-txt">P0 — Revenue &amp; Infrastructure Core System
</code></pre></body></html># 🚀 GitHub Issue: Enterprise-Grade Credit Economy, Wallet Billing & Cost Protection System for CommDesk


---

# 📌 Objective

Design and implement a **production-grade internal credit economy system** for [[CommDesk](https://commdesk.example.com/?utm_source=chatgpt.com)](https://commdesk.example.com?utm_source=chatgpt.com) that enables:

* Pay-as-you-go billing
* Community wallet management
* Real-time usage deduction
* Credit-based infrastructure abstraction
* Payout handling
* Revenue optimization
* AI/API future-proof monetization
* Enterprise-grade cost control

This system should support scaling from:

```txt id="2lswdb"
small communities → enterprise organizations → AI-powered SaaS ecosystem
```

---

# 🎯 Product Vision

Instead of charging users directly in rupees for every feature:

```txt id="9j9f1u"
Users purchase Credits → Credits are consumed by platform usage
```

This creates:

* Better UX
* Easier pricing management
* Infrastructure cost abstraction
* Easier AI monetization
* Better profit margins
* Cleaner analytics
* Enterprise scalability

---

# 💰 Official Credit Conversion System

## Final Conversion Model

```txt id="mb5vkw"
₹10 = 100 Credits
```

---

# ❌ Avoid

```txt id="ot0wdj"
₹10 = 10 Credits
```

Reason:

* Hard to micro-price features
* Decimal-heavy pricing
* Poor UX psychology
* Difficult AI/API pricing
* Weak future scaling

---

# ✅ Advantages of 100 Credits System

| Benefit        | Explanation                     |
| -------------- | ------------------------------- |
| Micro Billing  | Fine-grained pricing            |
| Better UX      | Users feel larger value         |
| Cleaner UI     | Avoid decimals                  |
| Easier Pricing | Flexible feature costing        |
| AI-Ready       | AI token pricing becomes easier |
| Revenue Safe   | Better margin control           |
| Scalable       | Supports enterprise billing     |

---

# 🧠 Core Architecture

---

# 1️⃣ Wallet System

## Main Wallet Features

Each user/community should have:

* Available Credits
* Pending Credits
* Locked Credits
* Reserved Credits
* Lifetime Purchased Credits
* Lifetime Consumed Credits

---

## Wallet Rules

| Rule              | Value    |
| ----------------- | -------- |
| Minimum Add Funds | ₹150     |
| Minimum Credits   | 1500     |
| Recharge Expiry   | Never    |
| Negative Balance  | Disabled |
| Decimal Credits   | Disabled |

---

# 🧱 Wallet Schema

```ts id="e9lmjh"
interface Wallet {
  id: string;

  ownerType: "user" | "community" | "organization";

  ownerId: string;

  availableCredits: number;

  lockedCredits: number;

  pendingCredits: number;

  reservedCredits: number;

  lifetimePurchasedCredits: number;

  lifetimeUsedCredits: number;

  autoRechargeEnabled: boolean;

  lowBalanceThreshold: number;

  createdAt: Date;

  updatedAt: Date;
}
```

---

# 2️⃣ Credit Transaction Ledger

## Goal

Every single credit movement must be traceable.

System should behave like:

* Banking ledger
* Stripe balance system
* AWS billing ledger

---

# Transaction Types

| Type             | Description              |
| ---------------- | ------------------------ |
| CREDIT_PURCHASE  | User bought credits      |
| USAGE_DEDUCTION  | Feature consumed credits |
| BONUS_CREDIT     | Promotional credits      |
| REFUND           | Payment refund           |
| PAYOUT_HOLD      | Locked during payout     |
| PAYOUT_RELEASE   | Released payout          |
| ADMIN_ADJUSTMENT | Manual admin action      |

---

# Ledger Schema

```ts id="jlwmcc"
interface CreditTransaction {
  id: string;

  walletId: string;

  transactionType:
    | "CREDIT_PURCHASE"
    | "USAGE_DEDUCTION"
    | "BONUS_CREDIT"
    | "REFUND"
    | "PAYOUT_HOLD"
    | "PAYOUT_RELEASE"
    | "ADMIN_ADJUSTMENT";

  credits: number;

  balanceBefore: number;

  balanceAfter: number;

  source: string;

  sourceId?: string;

  metadata?: Record<string, any>;

  createdAt: Date;
}
```

---

# 3️⃣ Community Wallet System

## Route

```bash id="8v21j2"
/dashboard/community/wallet
```

---

# Features

## Wallet Overview

Display:

```txt id="zj07gn"
Available Credits
Reserved Credits
Pending Credits
Estimated Burn Rate
Monthly Consumption
```

---

## Team Usage Breakdown

| Member | Credits Used | Last Activity |
| ------ | ------------ | ------------- |

---

## Shared Usage Tracking

Track:

* API usage
* AI usage
* Queue jobs
* Webhooks
* File storage
* Analytics generation

---

# 4️⃣ Credit Consumption Engine

## Goal

Centralized billing engine.

Every platform operation should pass through:

```txt id="0qt3gm"
Billing Consumption Service
```

---

# Example

```ts id="zv1ee6"
await BillingService.consumeCredits({
  walletId,
  feature: "AI_SUMMARY",
  credits: 15,
  metadata: {
    workspaceId,
    requestId
  }
});
```

---

# 🚨 Critical Requirement

NO feature should deduct credits manually.

Everything must go through centralized billing service.

---

# 5️⃣ Pricing Matrix

---

# Community Operations

| Action           | Credits |
| ---------------- | ------- |
| Create Community | Free    |
| Invite Member    | 1       |
| Update Branding  | 3       |
| Upload Banner    | 8       |
| Team Role Update | 1       |

---

# API Usage

| Operation       | Credits |
| --------------- | ------- |
| Basic Request   | 1       |
| Heavy Query     | 5       |
| Export Data     | 20      |
| Analytics Query | 10      |

---

# Queue & Background Jobs

| Job               | Credits |
| ----------------- | ------- |
| Email Send        | 1       |
| Push Notification | 1       |
| Retry Queue       | 2       |
| Scheduled Job     | 2       |

---

# Webhooks

| Action                 | Credits |
| ---------------------- | ------- |
| Webhook Trigger        | 1       |
| Retry Attempt          | 1       |
| Premium Queue Delivery | 3       |

---

# Storage

| Storage            | Credits |
| ------------------ | ------- |
| 100MB              | 5       |
| 1GB                | 40      |
| Media Optimization | 3       |

---

# AI Features

| Feature            | Credits |
| ------------------ | ------- |
| AI Summary         | 15      |
| AI Moderation      | 5       |
| AI Search          | 12      |
| AI Assistant Reply | 8       |

---

# 6️⃣ Add Funds Flow

## Route

```bash id="qv0r5o"
/billing/add-funds
```

---

# Add Funds Modal

## Fields

### Amount Input

```txt id="eot8c0"
Minimum ₹150
```

---

## Live Credit Preview

```txt id="7u2wqs"
You Pay: ₹500
GST: ₹90
Platform Fee: ₹12
Credits Added: 5500
Bonus Credits: 500
```

---

# Supported Payment Methods

* UPI
* Debit Card
* Credit Card
* Net Banking
* Wallets

---

# Payment States

| State      | Description           |
| ---------- | --------------------- |
| Idle       | Waiting               |
| Processing | Payment running       |
| Success    | Credits added         |
| Failed     | Payment failed        |
| Pending    | Awaiting confirmation |
| Refunded   | Payment refunded      |

---

# 7️⃣ Recharge Packs

## Starter Packs

| Amount | Credits | Bonus |
| ------ | ------- | ----- |
| ₹150   | 1500    | —     |
| ₹300   | 3200    | +200  |
| ₹500   | 5500    | +500  |
| ₹1000  | 12000   | +2000 |
| ₹2500  | 32000   | +7000 |

---

# 🧠 Psychological Pricing Strategy

Users psychologically prefer:

```txt id="ufg1uo"
5500 Credits
```

instead of:

```txt id="s9sm7m"
₹550 Usage Balance
```

This improves:

* Perceived value
* Spending comfort
* Recharge probability
* Retention

---

# 8️⃣ Auto Recharge System

## Features

Enable automatic recharge when balance drops below threshold.

---

# Example

```txt id="7s0t98"
If balance < 200 credits
Automatically recharge ₹150
```

---

# Requirements

* User configurable
* Payment method tokenization
* Failure retries
* Notification alerts

---

# 9️⃣ Usage Analytics Dashboard

## Route

```bash id="lbygu0"
/dashboard/usage
```

---

# Analytics Features

Track:

* Credit burn rate
* Daily usage
* Monthly usage
* Feature-wise consumption
* Storage growth
* API growth
* AI usage
* Queue usage

---

# Visualization

Use:

* Recharts
* ECharts
* Chart.js

---

# Analytics Widgets

## Burn Rate Card

```txt id="v5s1gf"
Estimated Monthly Spend: 12,500 Credits
```

---

## Top Consuming Features

| Feature | Credits Used |
| ------- | ------------ |

---

## Usage Forecasting

Predict:

* Next month cost
* AI usage spikes
* Storage expansion

---

# 🔒 Cost Protection & Abuse Prevention

---

# 1️⃣ Hard Usage Limits

Prevent:

* Infinite API abuse
* Queue flooding
* AI spam
* Webhook loops

---

# 2️⃣ Daily Caps

| Feature     | Daily Limit |
| ----------- | ----------- |
| AI Requests | 200         |
| Webhooks    | 10,000      |
| Emails      | 5,000       |

---

# 3️⃣ Suspicious Activity Detection

Flag:

* Rapid burn patterns
* Payment fraud
* Multi-account abuse
* Infinite retries

---

# 4️⃣ Graceful Credit Exhaustion

When credits run out:

* Pause premium features
* Keep core community accessible
* Show low balance modal

---

# 🔐 Security Requirements

---

# Billing Security

* Double-spend prevention
* Atomic deductions
* Idempotency keys
* Webhook signature verification
* Fraud scoring
* Replay attack prevention

---

# Database Safety

* Transactions mandatory
* Optimistic locking
* Ledger consistency validation
* Immutable transaction records

---

# 🏗️ Backend APIs

---

# Wallet APIs

```http id="wejlwm"
GET    /wallet
GET    /wallet/transactions
POST   /wallet/add-funds
POST   /wallet/consume
POST   /wallet/refund
```

---

# Analytics APIs

```http id="8wlsdq"
GET /usage/summary
GET /usage/breakdown
GET /usage/forecast
```

---

# Auto Recharge APIs

```http id="0jxh4o"
POST /wallet/auto-recharge/enable
POST /wallet/auto-recharge/disable
```

---

# 🧪 Testing Requirements

---

# Unit Tests

* Credit calculations
* Wallet deductions
* Refund logic
* Bonus credit logic
* Usage forecasting

---

# Integration Tests

* Payment → Wallet sync
* Deduction engine
* Retry handling
* Webhook validation

---

# E2E Tests

Using:

* Playwright
* Cypress

Scenarios:

* Add funds
* Failed payment
* Retry payment
* AI consumption
* Low balance alert
* Auto recharge

---

# 📱 UI/UX Requirements

---

# Design Inspiration

* [[Stripe Billing](https://stripe.com/?utm_source=chatgpt.com)](https://stripe.com?utm_source=chatgpt.com)
* [[AWS Billing Console](https://aws.amazon.com/billing/?utm_source=chatgpt.com)](https://aws.amazon.com/billing/?utm_source=chatgpt.com)
* [[Vercel Dashboard](https://vercel.com/?utm_source=chatgpt.com)](https://vercel.com?utm_source=chatgpt.com)
* [[Linear](https://linear.app/?utm_source=chatgpt.com)](https://linear.app?utm_source=chatgpt.com)

---

# Requirements

* Dark mode
* Fully responsive
* Skeleton loading
* Smooth animations
* Real-time updates
* Optimistic UI
* Mobile-first modal system

---

# ⚡ Performance Requirements

* Cached analytics
* Lazy loading
* Virtualized transaction tables
* Batched ledger writes
* SSE/WebSocket live updates

---

# 📈 Business Goal

Target infrastructure cost ratio:

```txt id="0ffv6x"
25–45% infra cost
35–50% gross margin
```

System should remain profitable even during:

* AI-heavy workloads
* High webhook usage
* Large communities
* Export-heavy operations

---

# ✅ Acceptance Criteria

* Fully working wallet system
* Centralized credit engine
* Immutable billing ledger
* Real-time analytics
* Add funds flow working
* Auto recharge implemented
* Abuse prevention active
* Production-grade security
* Full test coverage
* Mobile responsive UI
* Enterprise-ready scalability



Benefit	Explanation
Micro Billing	Fine-grained pricing
Better UX	Users feel larger value
Cleaner UI	Avoid decimals
Easier Pricing	Flexible feature costing
AI-Ready	AI token pricing becomes easier
Revenue Safe	Better margin control
Scalable	Supports enterprise billing

Rule	Value
Minimum Add Funds	₹150
Minimum Credits	1500
Recharge Expiry	Never
Negative Balance	Disabled
Decimal Credits	Disabled

Type	Description
CREDIT_PURCHASE	User bought credits
USAGE_DEDUCTION	Feature consumed credits
BONUS_CREDIT	Promotional credits
REFUND	Payment refund
PAYOUT_HOLD	Locked during payout
PAYOUT_RELEASE	Released payout
ADMIN_ADJUSTMENT	Manual admin action

Action	Credits
Create Community	Free
Invite Member	1
Update Branding	3
Upload Banner	8
Team Role Update	1

State	Description
Idle	Waiting
Processing	Payment running
Success	Credits added
Failed	Payment failed
Pending	Awaiting confirmation
Refunded	Payment refunded

Amount	Credits	Bonus
₹150	1500	—
₹300	3200	+200
₹500	5500	+500
₹1000	12000	+2000
₹2500	32000	+7000

feat(billing): Build Scalable Credit Economy, Community Wallet, Usage Billing & Cost-Control Infrastructure #95

Description

📌 Objective

🎯 Product Vision

💰 Official Credit Conversion System

Final Conversion Model

❌ Avoid

✅ Advantages of 100 Credits System

3️⃣ Suspicious Activity Detection

4️⃣ Graceful Credit Exhaustion

🔐 Security Requirements

Billing Security

Database Safety

🏗️ Backend APIs

Wallet APIs

Analytics APIs

Auto Recharge APIs

🧪 Testing Requirements

Unit Tests

Integration Tests

E2E Tests

📱 UI/UX Requirements

Design Inspiration

Requirements

⚡ Performance Requirements

📈 Business Goal

✅ Acceptance Criteria

🏷️ Labels

📌 Priority

📌 Objective

🎯 Product Vision

💰 Official Credit Conversion System

Final Conversion Model

❌ Avoid

✅ Advantages of 100 Credits System

🧠 Core Architecture

1️⃣ Wallet System

Main Wallet Features

Wallet Rules

🧱 Wallet Schema

2️⃣ Credit Transaction Ledger

Goal

Transaction Types

Ledger Schema

3️⃣ Community Wallet System

Route

Features

Wallet Overview

Team Usage Breakdown

Shared Usage Tracking

4️⃣ Credit Consumption Engine

Goal

Example

🚨 Critical Requirement

5️⃣ Pricing Matrix

Community Operations

API Usage

Queue & Background Jobs

Webhooks

Storage

AI Features

6️⃣ Add Funds Flow

Route

Add Funds Modal

Fields

Amount Input

Live Credit Preview

Supported Payment Methods

Payment States

7️⃣ Recharge Packs

Starter Packs

🧠 Psychological Pricing Strategy

8️⃣ Auto Recharge System

Features

Example

Requirements

9️⃣ Usage Analytics Dashboard

Route

Analytics Features

Visualization