feat: CommDesk Billing & Credit Economy Backend Infrastructure

use neon for postgress sql

# 📌 Objective

Build a complete enterprise-grade financial infrastructure for CommDesk capable of handling:

- UPI payments
- Wallet funding
- Credit system
- Community monetization
- Platform fee deduction
- Refunds
- Sponsor payments
- Partner settlements
- Auto recharge
- Billing
- Financial analytics
- Fraud prevention
- Queue-driven processing
- Audit-safe accounting
- Scalable SaaS monetization

The system must be designed similar to:

- Stripe Billing
- RazorpayX
- AWS Marketplace Billing
- Discord Billing
- Slack Billing
- Shopify Payments

---

# 🧠 Final Architecture Decision

## Database Strategy

CommDesk will use a hybrid database architecture.

---

# ✅ PostgreSQL (Primary Financial Database)

Used for:

- Payments
- Wallets
- Credits
- Ledger
- Billing
- Refunds
- Invoices
- Financial analytics
- Settlements
- Audit logs

---

# ✅ MongoDB (Existing Flexible Database)

Used for:

- Communities
- Events
- Posts
- Chats
- Activity feeds
- Flexible metadata
- Non-financial analytics

---

# ❌ Important Rule

```txt
NEVER store critical wallet balances
or financial ledger logic only in MongoDB.
```

---

# 🏆 Final Recommended Stack

| Layer | Technology |
|---|---|
| Backend | NestJS |
| Financial Database | PostgreSQL |
| PostgreSQL Hosting | Neon |
| Existing Database | MongoDB Atlas |
| ORM | Prisma |
| Payment Gateway | Cashfree |
| Queue System | RabbitMQ |
| Cache | Redis |
| Redis Hosting | Upstash |
| File Storage | Bunny.net |
| Monitoring | Grafana |
| Metrics | Prometheus |
| Error Tracking | Sentry |
| Tracing | OpenTelemetry |
| Containerization | Docker |
| Reverse Proxy | Traefik |
| CI/CD | GitHub Actions |

---

# ☁️ Cloud Providers

## PostgreSQL

### Neon

```txt
https://neon.tech
```

Required Features:

- Serverless PostgreSQL
- Connection pooling
- SSL support
- Branching
- Monitoring dashboard
- Auto scaling
- Prisma compatibility

---

## MongoDB

### MongoDB Atlas

```txt
https://mongodb.com/atlas
```

---

## Redis

### Upstash

```txt
https://upstash.com
```

---

## RabbitMQ

### CloudAMQP

```txt
https://cloudamqp.com
```

---

# 💳 Payment Gateway

# Cashfree Payments

```txt
https://cashfree.com
```

Required Support:

- UPI
- Cards
- Netbanking
- Wallets
- Refunds
- Webhooks
- Split settlements
- Vendor payouts
- Auto settlement
- Payment verification
- Subscription-ready APIs

---

# 💰 Billing Model

CommDesk uses a credit system.

```txt
₹10 = 100 Credits
```

---

# Recharge Packs

| Recharge | Credits |
|---|---|
| ₹150 | 1500 |
| ₹300 | 3200 |
| ₹500 | 5500 |
| ₹1000 | 12000 |

---

# 🏗️ High-Level Architecture

```txt
                           ┌────────────────────┐
                           │      Frontend      │
                           └─────────┬──────────┘
                                     │
                                     ▼
                           ┌────────────────────┐
                           │    API Gateway     │
                           └─────────┬──────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         ▼                           ▼                           ▼

┌──────────────────┐     ┌──────────────────┐      ┌──────────────────┐
│ Payment Service  │     │ Community API    │      │ Analytics API    │
└────────┬─────────┘     └────────┬─────────┘      └────────┬─────────┘
         │                        │                         │
         ▼                        ▼                         ▼

┌──────────────────┐     ┌──────────────────┐      ┌──────────────────┐
│ PostgreSQL       │     │ MongoDB Atlas    │      │ MongoDB          │
│ Financial DB     │     │ Community Data   │      │ Analytics        │
└──────────────────┘     └──────────────────┘      └──────────────────┘

         ▼
┌──────────────────┐
│ RabbitMQ         │
│ Queue System     │
└──────────────────┘

         ▼
┌──────────────────┐
│ Redis Cache      │
└──────────────────┘
```

---

# 🔥 Core Financial Rules

# NEVER

```txt
Trust frontend payment success response
```

---

# NEVER

```txt
Grant credits directly inside webhook controller
```

---

# NEVER

```txt
Update wallet balance without transaction locking
```

---

# ALWAYS

```txt
Verify payment using server-side verification
```

---

# ALWAYS

```txt
Use queue-driven payment processing
```

---

# ALWAYS

```txt
Write immutable ledger entries
```

---

# ALWAYS

```txt
Use atomic database transactions
```

---

# 🔒 Financial Safety Requirements

Required:

- ACID transactions
- Immutable ledger
- Double-spend prevention
- Row-level locking
- Replay-safe webhooks
- Idempotency keys
- Queue-driven processing
- Financial reconciliation
- Fraud scoring
- Duplicate prevention
- Distributed tracing
- Audit-safe logging

---

# 🗄️ Core Database Tables

Required tables:

```txt
users
wallets
wallet_transactions
ledger_entries
payments
payment_attempts
refunds
invoices
billing_events
subscriptions
usage_metering
community_settlements
fraud_events
audit_logs
payment_webhooks
```

---

# 🗃️ Prisma Schema Requirements

# Payment Model

```prisma
model Payment {
  id                    String   @id @default(uuid())

  userId                String

  orderId               String   @unique

  paymentSessionId      String?

  cashfreeOrderId       String?

  cashfreePaymentId     String?

  amount                Int

  creditsGranted        Int

  gstAmount             Int

  platformFee           Int

  currency              String   @default("INR")

  status                PaymentStatus

  paymentMethod         String?

  paymentGroup          String?

  customerPhone         String?

  customerEmail         String?

  metadata              Json?

  idempotencyKey        String   @unique

  webhookVerified       Boolean  @default(false)

  refunded              Boolean  @default(false)

  refundAmount          Int?

  fraudScore            Float?

  retryCount            Int      @default(0)

  createdAt             DateTime @default(now())

  updatedAt             DateTime @updatedAt

  @@index([userId])

  @@index([status])

  @@index([createdAt])

  @@map("payments")
}
```

---

# Wallet Model

```prisma
model Wallet {
  id                       String   @id @default(uuid())

  ownerId                  String

  availableCredits         Int      @default(0)

  lockedCredits            Int      @default(0)

  pendingCredits           Int      @default(0)

  lifetimePurchasedCredits BigInt   @default(0)

  autoRechargeEnabled      Boolean  @default(false)

  autoRechargeThreshold    Int      @default(200)

  createdAt                DateTime @default(now())

  updatedAt                DateTime @updatedAt

  transactions             CreditTransaction[]
}
```

---

# Immutable Ledger

```prisma
model CreditTransaction {
  id                 String   @id @default(uuid())

  walletId           String

  transactionType    CreditTransactionType

  credits            Int

  balanceBefore      Int

  balanceAfter       Int

  source             String

  sourceId           String?

  metadata           Json?

  idempotencyKey     String   @unique

  createdAt          DateTime @default(now())

  wallet             Wallet @relation(fields: [walletId], references: [id])

  @@index([walletId])

  @@index([createdAt])
}
```

---

# ⚡ Core Services

# Payment Service

Responsible for:

- Order creation
- Payment session generation
- Payment verification
- Refund handling
- Payment retries
- Settlement tracking
- Status synchronization

---

# Required Methods

```ts
createPaymentOrder()

createPaymentSession()

verifyPayment()

syncPaymentStatus()

refundPayment()

handleWebhook()

generateInvoice()

retryFailedPayment()
```

---

# Wallet Service

Responsible for:

- Credit grant
- Credit consumption
- Balance locking
- Auto recharge
- Refund credit reversal

---

# Required Methods

```ts
grantCredits()

consumeCredits()

refundCredits()

lockCredits()

releaseCredits()

syncBalance()
```

---

# Ledger Service

Responsible for:

- Immutable ledger writes
- Financial reconciliation
- Audit tracking
- Transaction history

---

# Fraud Service

Responsible for:

- Fraud scoring
- Duplicate payment detection
- Abuse detection
- Rate abuse tracking
- Risk profiling

---

# 💳 Payment Flow

# Order Creation

```txt
Frontend Request
   ↓
Backend Validation
   ↓
Create Payment Record
   ↓
Create Cashfree Order
   ↓
Generate Payment Session
   ↓
Return Hosted Payment Session
```

---

# Payment Success Flow

```txt
Cashfree Webhook
   ↓
Verify Signature
   ↓
Verify Payment Status
   ↓
Push Event To Queue
   ↓
Grant Credits
   ↓
Create Ledger Entry
   ↓
Update Wallet
   ↓
Trigger Analytics
   ↓
Send Notification
```

---

# 🚨 Critical Rule

# NEVER

```txt
Grant credits directly inside webhook controller
```

---

# ALWAYS

```txt
Publish successful payment event to queue
```

---

# ⚡ Queue Architecture

# Required Queues

| Queue | Purpose |
|---|---|
| payment.processing | Payment verification |
| wallet.credit | Wallet credit grant |
| wallet.debit | Credit consumption |
| refund.processing | Refund workflows |
| analytics.billing | Billing analytics |
| fraud.detection | Fraud analysis |
| webhook.processing | Webhook handling |
| invoice.generate | Invoice generation |
| notifications.billing | Notifications |
| settlements.processing | Community settlements |

---

# Queue Requirements

Required:

- Retry support
- Exponential backoff
- Dead-letter queues
- Idempotent consumers
- Queue monitoring
- Delayed jobs
- Queue recovery

---

# 🔄 Auto Recharge System

# Flow

```txt
Low Wallet Balance
        ↓
Trigger Recharge Event
        ↓
Create Cashfree Order
        ↓
Successful Payment
        ↓
Grant Credits
```

---

# Requirements

- Configurable thresholds
- Retry support
- Queue-based processing
- Failure alerts
- Usage monitoring

---

# 🔒 Security Requirements

# Payment Security

Required:

- Cashfree signature verification
- Idempotency keys
- Replay attack prevention
- Fraud scoring
- Duplicate prevention
- IP validation
- Device tracking
- Secure webhook verification

---

# Backend Security

Required:

- JWT auth
- RBAC
- CSRF protection
- HPP protection
- Abuse prevention
- Rate limiting
- API throttling

---

# ⚙️ Infrastructure Requirements

# Docker

Required:

- Dockerized services
- Multi-stage builds
- Production images
- Health checks

---

# CI/CD

Required:

- GitHub Actions
- Automated testing
- Prisma migrations
- Docker builds
- Vulnerability scanning

---

# Observability

Required:

| Tool | Purpose |
|---|---|
| Grafana | Dashboard |
| Prometheus | Metrics |
| Loki | Logs |
| Sentry | Error tracking |
| OpenTelemetry | Distributed tracing |

---

# 📊 Analytics Requirements

Track:

- Payment success rate
- Failed payments
- Recharge trends
- Revenue analytics
- Fraud attempts
- Refund spikes
- Queue lag
- Webhook failures
- Wallet inconsistencies
- Auto recharge usage

---

# 🚨 Alerting Requirements

Trigger alerts for:

- Failed webhooks
- Queue stuck
- Fraud spikes
- Negative balances
- High refund spikes
- PostgreSQL connection exhaustion
- Redis outage
- RabbitMQ failures

---

# 🧪 Production Testing Requirements

# Unit Tests

Test:

- Credit calculation
- GST calculation
- Wallet logic
- Ledger safety
- Refund logic
- Idempotency logic

---

# Integration Tests

Test:

- Cashfree integration
- Queue processing
- Webhook verification
- PostgreSQL transactions
- Redis integration
- RabbitMQ processing

---

# Failure Tests

Simulate:

- Duplicate webhooks
- Payment replay attacks
- Queue failures
- PostgreSQL deadlocks
- Redis outage
- RabbitMQ outage
- Fraud requests
- API abuse

---

# Load Testing

Simulate:

```txt
50K payments/minute
10M wallet transactions
1M webhook events/day
```

---

# 📁 Suggested Folder Structure

```bash
src/
 ├── modules/
 │    ├── payments/
 │    ├── billing/
 │    ├── wallet/
 │    ├── ledger/
 │    ├── fraud/
 │    ├── analytics/
 │    ├── invoices/
 │    ├── settlements/
 │    ├── auto-recharge/
 │    ├── webhooks/
 │    └── notifications/
 │
 ├── queues/
 ├── prisma/
 ├── telemetry/
 ├── middleware/
 ├── infrastructure/
 ├── common/
 ├── config/
 └── tests/
```

---

# 📦 Required Packages

# Core

```bash
npm install @prisma/client prisma
npm install zod uuid dotenv dayjs
npm install helmet compression cors
npm install pino pino-pretty
```

---

# Payments

```bash
npm install cashfree-pg
```

---

# Queue

```bash
npm install amqplib bullmq ioredis
```

---

# Monitoring

```bash
npm install @sentry/node
npm install prom-client
npm install @opentelemetry/api
```

---

# Security

```bash
npm install express-rate-limit
npm install rate-limiter-flexible
npm install csurf hpp
```

---

# ✅ Acceptance Criteria

- PostgreSQL financial infrastructure operational
- Neon database integrated
- MongoDB hybrid architecture implemented
- Cashfree integration complete
- UPI payment flow operational
- Queue-driven processing active
- Immutable ledger implemented
- Replay-safe webhooks implemented
- Fraud prevention enabled
- Auto recharge operational
- Refund engine operational
- Production monitoring active
- Observability setup complete
- Financial reconciliation system operational
- Horizontal scaling supported



---

# 📌 Priority

```txt
P0 — Core Revenue Infrastructure
```

Layer	Technology
Backend	NestJS
Financial Database	PostgreSQL
PostgreSQL Hosting	Neon
Existing Database	MongoDB Atlas
ORM	Prisma
Payment Gateway	Cashfree
Queue System	RabbitMQ
Cache	Redis
Redis Hosting	Upstash
File Storage	Bunny.net
Monitoring	Grafana
Metrics	Prometheus
Error Tracking	Sentry
Tracing	OpenTelemetry
Containerization	Docker
Reverse Proxy	Traefik
CI/CD	GitHub Actions

Queue	Purpose
payment.processing	Payment verification
wallet.credit	Wallet credit grant
wallet.debit	Credit consumption
refund.processing	Refund workflows
analytics.billing	Billing analytics
fraud.detection	Fraud analysis
webhook.processing	Webhook handling
invoice.generate	Invoice generation
notifications.billing	Notifications
settlements.processing	Community settlements

Tool	Purpose
Grafana	Dashboard
Prometheus	Metrics
Loki	Logs
Sentry	Error tracking
OpenTelemetry	Distributed tracing

feat: CommDesk Billing & Credit Economy Backend Infrastructure #24

Description

📌 Objective

🧠 Final Architecture Decision

Database Strategy

✅ PostgreSQL (Primary Financial Database)

✅ MongoDB (Existing Flexible Database)

❌ Important Rule

🏆 Final Recommended Stack

☁️ Cloud Providers

PostgreSQL

Neon

MongoDB

MongoDB Atlas

Redis

Upstash

RabbitMQ

CloudAMQP

💳 Payment Gateway

Cashfree Payments

💰 Billing Model

Recharge Packs

🏗️ High-Level Architecture

🔥 Core Financial Rules

NEVER

NEVER

NEVER

ALWAYS

ALWAYS

ALWAYS

ALWAYS

🔒 Financial Safety Requirements

🗄️ Core Database Tables

🗃️ Prisma Schema Requirements

Payment Model

Wallet Model

Immutable Ledger

⚡ Core Services

Payment Service

Required Methods

Wallet Service

Required Methods

Ledger Service

Fraud Service

💳 Payment Flow

Order Creation

Payment Success Flow

🚨 Critical Rule

NEVER

ALWAYS

⚡ Queue Architecture

Required Queues

Queue Requirements

🔄 Auto Recharge System

Flow

Requirements

🔒 Security Requirements

Payment Security

Backend Security

⚙️ Infrastructure Requirements

Docker

CI/CD

Observability

📊 Analytics Requirements

🚨 Alerting Requirements

🧪 Production Testing Requirements

Unit Tests

Integration Tests

Failure Tests

Load Testing

📁 Suggested Folder Structure

📦 Required Packages

Core

Payments

Queue

Monitoring

Security

✅ Acceptance Criteria

📌 Priority

Metadata