feat(finance): Build Production-Grade Revenue Split Engine with Platform Fee, GST, Cashfree Charges ; Role-Based Settlement System

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

<h1>📌 Objective</h1><p>Build a financial-grade revenue distribution infrastructure for <a href="https://commdesk.example.com/?utm_source=chatgpt.com">CommDesk</a> where:</p><ul><li><p>Any community can earn revenue</p></li><li><p>Revenue automatically splits across community roles</p></li><li><p>CommDesk platform fee is deducted automatically</p></li><li><p>Cashfree payment gateway charges are deducted</p></li><li><p>GST calculations are handled properly</p></li><li><p>Settlement accounting is audit-safe</p></li><li><p>Community members receive net earnings</p></li><li><p>Payout-ready internal wallets are maintained</p></li></ul><p>This system should behave similar to:</p><ul><li><p><a href="https://stripe.com/connect?utm_source=chatgpt.com">Stripe Connect</a></p></li><li><p><a href="https://razorpay.com/route/?utm_source=chatgpt.com">Razorpay Route</a></p></li><li><p><a href="https://www.shopify.com/partners?utm_source=chatgpt.com">Shopify Partner Payouts</a></p></li></ul><hr><h1>🎯 Core Goals</h1><p>The system must support:</p><ul><li><p>Platform fee deduction</p></li><li><p>GST calculations</p></li><li><p>Cashfree charge deduction</p></li><li><p>Dynamic revenue splitting</p></li><li><p>Role-based earnings</p></li><li><p>Community settlements</p></li><li><p>Internal earning wallets</p></li><li><p>Financial-safe accounting</p></li><li><p>Tax-ready ledger system</p></li><li><p>Audit-safe payout infrastructure</p></li></ul><hr><h1>💰 Financial Flow</h1><p>Before ANY community distribution:</p><pre><code class="language-txt">Customer Payment
      ↓
GST Deduction
      ↓
Cashfree Charges
      ↓
Platform Fee
      ↓
Net Community Revenue
      ↓
Role-Based Split
      ↓
Wallet Distribution
</code></pre><hr><h1>🧠 Example Revenue Calculation</h1><hr><h1>Example 1 — Event Revenue</h1><pre><code class="language-txt">Customer Pays = ₹10,000

GST (18%) = ₹1,800

Remaining = ₹8,200

Cashfree Charges:
2% + GST = ₹193

Remaining = ₹8,007

CommDesk Platform Fee:
10% = ₹800

Net Community Revenue:
₹7,207
</code></pre><hr><h1>Role Distribution</h1><pre><code class="language-txt">Owner = 50% = ₹3,603.5

Admin Team = 20% = ₹1,441.4

Moderator Team = 10% = ₹720.7

Event Team = 20% = ₹1,441.4
</code></pre><hr><h1>Example 2 — Sponsor Revenue</h1><pre><code class="language-txt">Sponsor Payment = ₹50,000

GST = ₹9,000

Remaining = ₹41,000

Cashfree Fee = ₹968

Remaining = ₹40,032

Platform Fee (12%) = ₹4,803

Community Pool = ₹35,229
</code></pre><hr><h1>🏗️ Revenue Split Architecture</h1><pre><code class="language-txt">Customer Payment
        ↓
Cashfree Verification
        ↓
Financial Calculation Engine
        ↓
GST Deduction
        ↓
Gateway Charge Deduction
        ↓
Platform Fee Deduction
        ↓
Net Revenue Pool
        ↓
Role Distribution Engine
        ↓
Role Wallet Credit
        ↓
Settlement Queue
</code></pre><hr><h1>🧱 Backend Stack</h1><hr><h1>Runtime</h1><pre><code class="language-txt">Node.js + TypeScript
</code></pre><hr><h1>Framework</h1><p>Preferred:</p><ul><li><p><a href="https://nestjs.com/?utm_source=chatgpt.com">NestJS</a></p></li></ul><hr><h1>Database</h1><p>Preferred:</p><ul><li><p><a href="https://postgresql.org/?utm_source=chatgpt.com">PostgreSQL</a></p></li></ul><hr><h1>ORM</h1><p>Preferred:</p><ul><li><p><a href="https://prisma.io/?utm_source=chatgpt.com">Prisma</a></p></li></ul><hr><h1>Queue</h1><p>Preferred:</p><ul><li><p><a href="https://rabbitmq.com/?utm_source=chatgpt.com">RabbitMQ</a></p></li></ul><hr><h1>Cache</h1><ul><li><p><a href="https://redis.io/?utm_source=chatgpt.com">Redis</a></p></li></ul><hr><h1>Payment Provider</h1><ul><li><p><a href="https://www.cashfree.com/?utm_source=chatgpt.com">Cashfree Payments</a></p></li></ul><hr><h1>📦 Required Packages</h1><hr><h1>Core</h1><pre><code class="language-bash">npm install @prisma/client prisma
npm install zod uuid dotenv dayjs
npm install helmet cors compression
npm install pino pino-pretty
</code></pre><hr><h1>Queue</h1><pre><code class="language-bash">npm install amqplib bullmq ioredis
</code></pre><hr><h1>Cashfree</h1><pre><code class="language-bash">npm install cashfree-pg
</code></pre><hr><h1>Security</h1><pre><code class="language-bash">npm install express-rate-limit
npm install rate-limiter-flexible
npm install csurf hpp
</code></pre><hr><h1>🗄️ Core Database Schemas</h1><hr><h1>Community Wallet</h1><pre><code class="language-prisma">model CommunityWallet {
  id                         String   @id @default(uuid())

  communityId               String   @unique

  availableBalance          Int      @default(0)

  lockedBalance             Int      @default(0)

  pendingSettlement         Int      @default(0)

  totalGrossRevenue         BigInt   @default(0)

  totalPlatformFees         BigInt   @default(0)

  totalGatewayFees          BigInt   @default(0)

  totalGSTCollected         BigInt   @default(0)

  totalNetRevenue           BigInt   @default(0)

  totalWithdrawn            BigInt   @default(0)

  createdAt                 DateTime @default(now())

  updatedAt                 DateTime @updatedAt
}
</code></pre><hr><h1>Revenue Transaction Ledger</h1><pre><code class="language-prisma">model RevenueTransaction {
  id                         String   @id @default(uuid())

  communityId               String

  sourceType                RevenueSourceType

  sourceId                  String

  grossAmount               Int

  gstAmount                 Int

  paymentGatewayFee         Int

  paymentGatewayGST         Int

  platformFee               Int

  platformFeeGST            Int

  netRevenue                Int

  metadata                  Json?

  idempotencyKey            String   @unique

  createdAt                 DateTime @default(now())

  @@index([communityId])

  @@index([createdAt])
}
</code></pre><hr><h1>Role Distribution Table</h1><pre><code class="language-prisma">model RevenueDistribution {
  id                         String   @id @default(uuid())

  transactionId             String

  userId                    String

  roleId                    String

  roleName                  String

  percentage                Float

  amount                    Int

  createdAt                 DateTime @default(now())

  @@index([transactionId])

  @@index([userId])
}
</code></pre><hr><h1>Platform Revenue Table</h1><pre><code class="language-prisma">model PlatformRevenue {
  id                         String   @id @default(uuid())

  transactionId             String

  amount                    Int

  gstAmount                 Int

  feePercentage             Float

  createdAt                 DateTime @default(now())
}
</code></pre><hr><h1>💸 Financial Calculation Engine</h1><hr><h1>Required Flow</h1><pre><code class="language-txt">Gross Revenue
   ↓
GST Extraction
   ↓
Cashfree Charges
   ↓
Cashfree GST
   ↓
CommDesk Platform Fee
   ↓
Platform GST
   ↓
Net Revenue Pool
   ↓
Role Distribution
</code></pre><hr><h1>Required Service Methods</h1><pre><code class="language-ts">calculateGST()

calculateGatewayFees()

calculatePlatformFee()

calculateNetRevenue()

splitRevenueAcrossRoles()

creditRoleWallets()

createLedgerEntries()
</code></pre><hr><h1>⚡ Dynamic Fee System</h1><hr><h1>Admin Configurable</h1>
Setting | Example
-- | --
Platform Fee | 5–20%
Sponsor Fee | Custom
Event Fee | Custom
Premium Community Fee | Custom
GST Percentage | 18%

<hr><h1>Queue Rules</h1><p>Required:</p><ul><li><p>Retry support</p></li><li><p>Exponential backoff</p></li><li><p>Dead-letter queues</p></li><li><p>Delayed retries</p></li><li><p>Idempotent consumers</p></li></ul><hr><h1>📊 Analytics Requirements</h1><p>Track:</p><ul><li><p>Gross revenue</p></li><li><p>Net revenue</p></li><li><p>Platform earnings</p></li><li><p>Gateway charges</p></li><li><p>GST collected</p></li><li><p>Community earnings</p></li><li><p>Top earning communities</p></li><li><p>Payout volume</p></li></ul><hr><h1>📈 Dashboard Features</h1><p>Users should see:</p><ul><li><p>Gross revenue</p></li><li><p>Platform fee breakdown</p></li><li><p>Cashfree fee breakdown</p></li><li><p>GST deductions</p></li><li><p>Net earnings</p></li><li><p>Revenue split analytics</p></li><li><p>Wallet history</p></li><li><p>Monthly reports</p></li></ul><hr><h1>🧪 Testing Requirements</h1><hr><h1>Unit Tests</h1><p>Test:</p><ul><li><p>GST calculations</p></li><li><p>Platform fee calculations</p></li><li><p>Gateway fee calculations</p></li><li><p>Revenue splitting</p></li><li><p>Settlement generation</p></li></ul><hr><h1>Integration Tests</h1><p>Test:</p><ul><li><p>Cashfree integration</p></li><li><p>Revenue distribution</p></li><li><p>Wallet synchronization</p></li><li><p>Queue processing</p></li></ul><hr><h1>Failure Tests</h1><p>Test:</p><ul><li><p>Duplicate payouts</p></li><li><p>Queue crash</p></li><li><p>DB deadlock</p></li><li><p>Cashfree downtime</p></li><li><p>Partial transaction failures</p></li></ul><hr><h1>Load Testing</h1><p>Simulate:</p><pre><code class="language-txt">100K financial split events/min
</code></pre><hr><h1>📈 Monitoring &amp; Alerts</h1><hr><h1>Metrics</h1><p>Track:</p><ul><li><p>Revenue throughput</p></li><li><p>Settlement delays</p></li><li><p>Failed payouts</p></li><li><p>Fraud attempts</p></li><li><p>Queue lag</p></li><li><p>Wallet inconsistencies</p></li></ul><hr><h1>Alerts</h1><p>Trigger alerts for:</p><ul><li><p>Failed settlements</p></li><li><p>High fraud activity</p></li><li><p>Queue failures</p></li><li><p>Negative balances</p></li><li><p>Payment inconsistencies</p></li></ul><hr><h1>🗂️ Suggested Folder Structure</h1><pre><code class="language-bash">src/
 ├── modules/
 │    ├── revenue-engine/
 │    ├── gst-engine/
 │    ├── gateway-fees/
 │    ├── settlements/
 │    ├── payouts/
 │    ├── role-wallets/
 │    ├── fraud-detection/
 │    └── finance-analytics/
 │
 ├── queues/
 ├── telemetry/
 ├── middleware/
 ├── prisma/
 ├── common/
 └── tests/
</code></pre><hr><h1>✅ Acceptance Criteria</h1><ul><li><p>Platform fee deduction implemented</p></li><li><p>GST calculations implemented</p></li><li><p>Cashfree charge deduction implemented</p></li><li><p>Role-based revenue splitting implemented</p></li><li><p>Immutable ledger implemented</p></li><li><p>Settlement system implemented</p></li><li><p>Cashfree payout integration working</p></li><li><p>Queue-driven architecture enabled</p></li><li><p>Fraud prevention active</p></li><li><p>Full observability setup</p></li><li><p>Production-grade testing completed</p></li><li><p>Horizontally scalable architecture supported</p></li></ul></pre><hr><h1>📌 Priority</h1><pre><code class="language-txt">P0 — Financial Infrastructure Core
</code></pre></body></html>

Setting	Example
Platform Fee	5–20%
Sponsor Fee	Custom
Event Fee	Custom
Premium Community Fee	Custom
GST Percentage	18%

feat(finance): Build Production-Grade Revenue Split Engine with Platform Fee, GST, Cashfree Charges ; Role-Based Settlement System #25

Description

📌 Objective

🎯 Core Goals

💰 Financial Flow

🧠 Example Revenue Calculation

Example 1 — Event Revenue

Role Distribution

Example 2 — Sponsor Revenue

🏗️ Revenue Split Architecture

🧱 Backend Stack

Runtime

Framework

Database

ORM

Queue

Cache

Payment Provider

📦 Required Packages

Core

Queue

Cashfree

Security

🗄️ Core Database Schemas

Community Wallet

Revenue Transaction Ledger

Role Distribution Table

Platform Revenue Table

💸 Financial Calculation Engine

Required Flow

Required Service Methods

⚡ Dynamic Fee System

Admin Configurable

Queue Rules

📊 Analytics Requirements

📈 Dashboard Features

🧪 Testing Requirements

Unit Tests

Integration Tests

Failure Tests

Load Testing

📈 Monitoring & Alerts

Metrics

Alerts

🗂️ Suggested Folder Structure

✅ Acceptance Criteria

📌 Priority

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions