Credit System Implementation - Backend

Overview

Complete implementation of a credit-based system for managing startup access to government signals and connections.

---

🎯 What Was Implemented

1. Database Schema (packages/database/prisma/schema.prisma)

Added Fields to StartupContact Model:

creditsTotal              Int       @default(100)
creditsUsed               Int       @default(0)
creditsRemaining          Int       @default(100)
monthlyAllocation         Int       @default(100)
lastCreditReset           DateTime?
creditTier                String    @default("basic")

New Models:

• CreditTransaction: Tracks all credit usage and additions
• CreditConfiguration: Defines credit costs per action
• CreditTier: Manages subscription tiers (free, basic, premium, unlimited)

2. Services

CreditService (apps/backend/src/services/credit.service.ts)

Core credit operations:

• getStartupCredits() - Get credit balance
• getCreditsByEmail() - Get credits by user email
• hasCredits() - Check if sufficient credits available
• consumeCredits() - Deduct credits for actions
• addCredits() - Admin add credits
• deductCredits() - Admin deduct credits
• getCreditHistory() - Get transaction history
• getCreditConfiguration() - Get action costs
• updateMonthlyAllocation() - Update allocation
• updateCreditTier() - Change subscription tier
• resetMonthlyCreditsForStartup() - Manual reset
• resetMonthlyCreditsForAllStartups() - Automated monthly reset (runs 1st of each month)
• getCreditStatistics() - Analytics for startup

CreditManagementService (apps/backend/src/admin/credit-management.service.ts)

Admin operations:

• getAllStartupsWithCredits() - List all startups with filters
• getStartupCreditDetails() - Detailed credit info
• bulkAddCredits() - Bulk add to multiple startups
• bulkDeductCredits() - Bulk deduct from multiple
• updateCreditConfiguration() - Update action costs
• getCreditAnalytics() - Comprehensive analytics
• getAllCreditTransactions() - All transactions with filters
• upsertCreditTier() - Create/update tiers
• getStartupsNeedingAttention() - Low/exhausted credits
• exportCreditData() - Export for reporting

3. API Endpoints

User Endpoints (/credits)

GET    /credits/balance        Get current credit balance
GET    /credits/history        Get transaction history
GET    /credits/config         Get credit costs per action
GET    /credits/statistics     Get credit usage statistics
GET    /credits/tiers          Get available subscription tiers

Admin Endpoints (/admin/credits)

GET    /admin/credits/startups                  List all startups
GET    /admin/credits/startups/:id              Get startup details
POST   /admin/credits/startups/:id/add          Add credits
POST   /admin/credits/startups/:id/deduct       Deduct credits
POST   /admin/credits/bulk/add                  Bulk add credits
POST   /admin/credits/bulk/deduct               Bulk deduct credits
PUT    /admin/credits/startups/:id/allocation   Update monthly allocation
PUT    /admin/credits/startups/:id/tier         Update tier
GET    /admin/credits/analytics                 Get analytics
GET    /admin/credits/transactions              Get all transactions
PUT    /admin/credits/config                    Update action costs
PUT    /admin/credits/tiers                     Create/update tier
GET    /admin/credits/attention                 Get startups needing attention
POST   /admin/credits/startups/:id/reset        Reset monthly credits
GET    /admin/credits/export                    Export credit data

4. DTOs (apps/backend/src/dto/credit.dto.ts)

Complete validation and Swagger documentation for all endpoints

5. Credit Configuration

Default action costs (configurable via admin):

• signal_pool_request: 10 credits
• connection_request: 15 credits
• signal_view_details: 5 credits
• warm_intro_request: 20 credits
• priority_matching: 25 credits

6. Credit Tiers

Tier	Monthly Credits	Features
Free	50	Basic access
Basic	100	Standard access + signal pool
Premium	250	Enhanced access + priority matching
Unlimited	∞	All features + white-glove service

7. Automated Features

• Monthly Reset: Automatic credit reset on 1st of each month at midnight
• Transaction Logging: All credit changes are logged with full audit trail
• Balance Tracking: Real-time balance calculations

---

🗄️ Database Changes Applied

• ✅ Schema updated with credit fields
• ✅ New tables created: credit_transactions, credit_configurations, credit_tiers
• ✅ All 10 existing startups updated with default credits (100 credits, basic tier)
• ✅ Seed data populated:
  • 4 credit tiers
  • 5 credit configurations
  • 10 startups initialized

---

📦 Files Created/Modified

Created Files:

apps/backend/src/
├── services/
│   └── credit.service.ts                    (Core credit operations)
├── admin/
│   ├── credit-management.service.ts         (Admin operations)
│   └── admin-credit.controller.ts           (Admin API)
├── controllers/
│   └── credit.controller.ts                 (User API)
├── dto/
│   └── credit.dto.ts                        (Validation & Swagger)
├── modules/
│   └── credit.module.ts                     (Module configuration)
└── scripts/
    └── seed-credit-data.ts                  (Database seeding)

packages/database/
└── prisma/schema.prisma                     (Updated with credit models)

Modified Files:

apps/backend/src/app.module.ts               (Added CreditModule)
packages/database/index.ts                   (Exported credit types)

---

🚀 How to Use

For Users (Frontend Integration Needed):

// Get credit balance
GET /credits/balance
Response: {
  creditsTotal: 100,
  creditsUsed: 30,
  creditsRemaining: 70,
  creditTier: "basic"
}

// View history
GET /credits/history?limit=20

For Admins:

// View all startups with credits
GET /admin/credits/startups?tier=basic&sortBy=creditsRemaining

// Add credits to a startup
POST /admin/credits/startups/{id}/add
Body: { amount: 50, reason: "Bonus credits for early adopter" }

// Get analytics
GET /admin/credits/analytics?startDate=2025-01-01&tier=premium

Consuming Credits in Your Code:

// Example: Before allowing a connection request
const creditCost = await creditService.getActionCost("connection_request");
const hasCredits = await creditService.hasCredits(startupId, creditCost);

if (!hasCredits) {
  throw new BadRequestException("Insufficient credits");
}

// Consume credits when action is performed
await creditService.consumeCredits({
  startupId,
  actionType: "connection_request",
  amount: creditCost,
  entityId: connectionId,
  entityType: "connection",
  description: "Connection request to government contact",
});

---

🔄 Next Steps (For Complete Implementation)

1. Frontend Integration (Apps/frontend)

• Update sidebar to fetch dynamic credit data from /credits/balance
• Create credit history page
• Add low credit warnings
• Create admin credit management dashboard

2. Integration with Existing Features

• Add credit checks to signal pool requests
• Add credit consumption to connection requests
• Add credit checks to warm intro requests
• Update signal viewing to consume credits if configured

3. Admin Dashboard

• Create admin UI for viewing all startups
• Create UI for adding/deducting credits
• Create analytics dashboard
• Create tier management interface

4. Notifications

• Email notifications when credits are low (< 10)
• Email notifications on monthly reset
• Admin alerts for exhausted startups

5. Testing

• Unit tests for CreditService
• Unit tests for CreditManagementService
• E2E tests for credit endpoints
• Integration tests with signal/connection features

---

🧪 Testing the Backend

Manual Testing:

# Start backend
pnpm dev:backend

# Test user endpoints (requires authentication)
curl http://localhost:3800/credits/balance \
  -H "Authorization: Bearer YOUR_TOKEN"

# Test admin endpoints
curl http://localhost:3800/admin/credits/startups \
  -H "Authorization: Bearer ADMIN_TOKEN"

Run Seed Script:

cd apps/backend
npx ts-node src/scripts/seed-credit-data.ts

---

📊 Credit Transaction Flow

User Action → Check Credits → Consume Credits → Log Transaction → Update Balance
                    ↓                                    ↓
              Insufficient?                      Create Audit Trail
                    ↓
              Reject Action

---

🔐 Security Considerations

1. Authentication: All endpoints protected by ClerkAuthGuard
2. Authorization: Admin endpoints should have additional role checks
3. Transaction Integrity: All credit operations use database transactions
4. Audit Trail: Complete transaction history for accountability
5. Validation: All inputs validated with class-validator

---

💡 Key Features

✅ Complete CRUD operations for credits ✅ Automated monthly reset with cron job ✅ Flexible tier system ✅ Configurable action costs ✅ Comprehensive analytics ✅ Bulk operations for admins ✅ Full audit trail ✅ Type-safe with TypeScript ✅ Swagger documentation ✅ Transaction safety with Prisma

---

📝 Notes

• Unlimited Tier: Startups on unlimited tier bypass all credit checks
• Monthly Reset: Happens automatically on 1st of each month at midnight
• Credit Configuration: Admins can change action costs without code changes
• Transaction History: Permanent record of all credit changes
• Balance Consistency: Real-time calculation ensures accuracy

---

🐛 Troubleshooting

Credits not updating?

• Check if startup exists in database
• Verify creditTier is not "unlimited"
• Check transaction logs for errors

Monthly reset not working?

• Verify ScheduleModule is imported
• Check backend logs for cron execution
• Ensure backend is running continuously

Build errors?

• Run pnpm db:generate after schema changes
• Run pnpm db:push to sync database
• Clear node_modules and reinstall if needed

---

📚 Additional Resources

• Prisma Documentation
• NestJS Scheduling
• Class Validator

---

Implementation Date: October 16, 2025 Status: ✅ Backend Complete - Frontend Integration Pending Database: ✅ Seeded and Ready API: ✅ Fully Functional