Normalized for Mintlify from knowledge-base/aiconnected-apps-and-modules/modules/funnelChat/legacy-funnelChat-readme.mdx.

funnelChat by aiConnected

> An AI-powered chatbot platform for debt collection and accounts receivable management

📋 Table of Contents

Overview
Features
Architecture
Tech Stack
Prerequisites
Installation
Configuration
Development
Testing
Deployment
API Documentation
Contributing
License

🎯 Overview

funnelChat is a comprehensive AI chatbot platform designed specifically for the debt collection and accounts receivable industry. It provides automated, compliant, and empathetic communication with debtors across multiple channels while giving businesses powerful tools to manage their collections process.

What Does This Platform Do?

For Debtors (Public-Facing):

Receive payment reminders via SMS, WhatsApp, email, and web chat
Negotiate payment plans through conversational AI
Make payments securely
Request payment plan modifications
Access account information 24/7

For Businesses (Back-End):

Manage debtor accounts and communication
Monitor AI chatbot conversations
Configure automated workflows
Track payment analytics and recovery rates
Ensure regulatory compliance (FDCPA, TCPA, CFPB)
Generate compliance reports

✨ Features

Core Features

1. Multi-Channel Communication

SMS Chatbot - Text message conversations
WhatsApp Integration - Global messaging support
Email Bot - Automated email responses
Web Widget - Embedded chat on customer portals
Voice Bot - IVR integration for phone calls

2. AI-Powered Conversations

Natural language understanding
Sentiment analysis
Empathetic response generation
Multi-language support (English, Spanish)
Context-aware dialogue management

3. Payment Management

Secure payment processing via Stripe
Dynamic payment plan generation
Automated payment reminders
Failed payment retry logic
Settlement offer calculations

4. Compliance & Security

Real-time FDCPA compliance checking
Automated audit trails
Encrypted data storage
PCI DSS compliant payment handling
TCPA consent management

5. Analytics & Reporting

Real-time dashboards
Recovery rate tracking
Channel performance metrics
Debtor engagement analytics
Compliance reports

🏗️ Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    FRONT-END LAYER                          │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Debtor Portal│  │ Business App │  │ Admin Panel  │     │
│  │  (React.js)  │  │  (React.js)  │  │  (React.js)  │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                     API GATEWAY LAYER                       │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────┐  │
│  │         Node.js/Express API Gateway                   │  │
│  │  - Authentication & Authorization                     │  │
│  │  - Rate Limiting                                      │  │
│  │  - Request Routing                                    │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   APPLICATION LAYER                         │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │Chatbot   │  │ Payment  │  │Analytics │  │Compliance│  │
│  │Service   │  │ Service  │  │ Service  │  │ Service  │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   INTEGRATION LAYER                         │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Twilio   │  │  Stripe  │  │ Anthropic│  │SendGrid  │  │
│  │ (SMS/WA) │  │(Payments)│  │  (AI)    │  │ (Email)  │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                      DATA LAYER                             │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │  PostgreSQL  │  │    Redis     │  │      S3      │    │
│  │ (Primary DB) │  │   (Cache)    │  │ (File Store) │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────────────────────────┘

System Components

Front-End Applications

Debtor Portal - Public-facing chat interface for debtors
Business Dashboard - Collection agent interface
Admin Panel - System configuration and management

Back-End Services

API Gateway - Central request router and authenticator
Chatbot Service - AI conversation orchestration
Payment Service - Payment processing and plan management
Analytics Service - Data aggregation and reporting
Compliance Service - Regulatory monitoring and enforcement
Notification Service - Multi-channel message delivery

🛠️ Tech Stack

Front-End

Framework: React 18+ with TypeScript
State Management: Redux Toolkit
UI Components: Material-UI (MUI) v5
Routing: React Router v6
Form Management: React Hook Form
Data Fetching: React Query (TanStack Query)
Charts: Recharts
Real-time: Socket.io Client

Back-End

Runtime: Node.js 20 LTS
Framework: Express.js 4.18+
Language: TypeScript 5.0+
API Documentation: OpenAPI 3.0 (Swagger)
WebSockets: Socket.io 4.0+
Job Queue: Bull (Redis-based)
Validation: Joi / Zod

Database

Primary Database: PostgreSQL 15+
ORM: Prisma 5.0+
Cache: Redis 7.0+
Search: PostgreSQL Full-Text Search

AI & NLP

LLM Provider: Anthropic Claude API
Model: Claude Sonnet 4
Prompt Management: Custom prompt templates
Sentiment Analysis: Custom Claude prompts

Third-Party Integrations

Payments: Stripe API
SMS/WhatsApp: Twilio API
Email: SendGrid API
File Storage: AWS S3 or compatible
Monitoring: Datadog / New Relic (optional)

Infrastructure

Containerization: Docker
Orchestration: Docker Compose (dev), Kubernetes (prod)
CI/CD: GitHub Actions
Hosting: AWS / DigitalOcean / Render
CDN: CloudFlare

Development Tools

Version Control: Git
Package Manager: npm or pnpm
Code Quality: ESLint, Prettier
Testing: Jest, Supertest, React Testing Library
API Testing: Postman / Insomnia

📦 Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Node.js: v20.0.0 or higher (Download)
PostgreSQL: v15 or higher (Download)
Redis: v7.0 or higher (Download)
Git: Latest version (Download)
Docker: Latest version (Download) - Optional but recommended

Required API Keys

You’ll need to sign up and obtain API keys from:

Anthropic - For Claude AI (https://console.anthropic.com/)
Stripe - For payment processing (https://stripe.com/)
Twilio - For SMS/WhatsApp (https://www.twilio.com/)
SendGrid - For email (https://sendgrid.com/)

Development Skills

JavaScript/TypeScript basics
Understanding of REST APIs
Basic SQL knowledge
Familiarity with Git commands

🚀 Installation

Option 1: Docker Setup (Recommended for Beginners)

Clone the repository

git clone https://github.com/your-org/funnelchat.git
cd funnelchat

Copy environment variables

cp .env.example .env

Edit the .env file with your API keys

# Use your favorite text editor
nano .env
# or
code .env

Start all services with Docker

docker-compose up -d

Run database migrations

docker-compose exec api npm run migrate

Seed the database (optional, for test data)

docker-compose exec api npm run seed

Access the applications

Debtor Portal: http://localhost:3000
Business Dashboard: http://localhost:3001
Admin Panel: http://localhost:3002
API: http://localhost:4000

Option 2: Manual Setup

Step 1: Clone Repository

git clone https://github.com/your-org/funnelchat.git
cd funnelchat

Step 2: Install Dependencies

Install backend dependencies:

cd backend
npm install

Install frontend dependencies:

# Debtor Portal
cd ../frontend/debtor-portal
npm install

# Business Dashboard
cd ../business-dashboard
npm install

# Admin Panel
cd ../admin-panel
npm install

Step 3: Setup Database

Create PostgreSQL database:

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE funnelchat_dev;

# Create user
CREATE USER funnelchat_user WITH PASSWORD 'your_secure_password';

# Grant privileges
GRANT ALL PRIVILEGES ON DATABASE funnelchat_dev TO funnelchat_user;

# Exit
\q

Create Redis database:

# Redis typically doesn't require database creation
# Just ensure Redis is running
redis-cli ping
# Should return: PONG

Step 4: Configure Environment Variables

Backend (.env):

cd backend
cp .env.example .env

Edit the .env file:

# Application
NODE_ENV=development
PORT=4000
APP_URL=http://localhost:4000

# Database
DATABASE_URL=postgresql://funnelchat_user:your_secure_password@localhost:5432/funnelchat_dev

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET=your_very_long_random_secret_key_change_this
JWT_EXPIRES_IN=7d

# Anthropic Claude
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Stripe
STRIPE_SECRET_KEY=your_stripe_secret_key_here
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret_here

# Twilio
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=+1234567890
TWILIO_WHATSAPP_NUMBER=+1234567890

# SendGrid
SENDGRID_API_KEY=your_sendgrid_api_key
SENDGRID_FROM_EMAIL=noreply@funnelchat.com

# AWS S3 (optional)
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret
AWS_REGION=us-east-1
AWS_S3_BUCKET=funnelchat-files

# Compliance
ENABLE_COMPLIANCE_MODE=true
AUDIT_LOG_RETENTION_DAYS=2555

Frontend applications (.env): For each frontend app (debtor-portal, business-dashboard, admin-panel):

cd frontend/debtor-portal
cp .env.example .env

Edit:

REACT_APP_API_URL=http://localhost:4000
REACT_APP_WS_URL=ws://localhost:4000
REACT_APP_STRIPE_PUBLIC_KEY=your_stripe_public_key

Step 5: Run Database Migrations

cd backend
npm run migrate

This will create all necessary database tables.

Step 6: Seed Database (Optional)

npm run seed

This creates test data including:

Admin user (admin@funnelchat.com / admin123)
Sample business accounts
Sample debtor accounts
Sample payment plans

Step 7: Start Development Servers

Terminal 1 - Backend API:

cd backend
npm run dev

Terminal 2 - Debtor Portal:

cd frontend/debtor-portal
npm start

Terminal 3 - Business Dashboard:

cd frontend/business-dashboard
npm start

Terminal 4 - Admin Panel:

cd frontend/admin-panel
npm start

Terminal 5 - Background Jobs (optional):

cd backend
npm run worker

⚙️ Configuration

Environment Variables Explained

Critical Security Settings

JWT_SECRET - Used to sign authentication tokens. MUST be unique and random (at least 32 characters)
STRIPE_WEBHOOK_SECRET - Validates Stripe webhook authenticity
Database passwords should be strong and unique

API Keys

Each service requires an API key:

Anthropic: Get from https://console.anthropic.com/
Stripe: Get from https://dashboard.stripe.com/apikeys
Twilio: Get from https://console.twilio.com/
SendGrid: Get from https://app.sendgrid.com/settings/api_keys

Feature Flags

Toggle features on/off:

ENABLE_COMPLIANCE_MODE=true          # Enable FDCPA compliance checking
ENABLE_VOICE_BOT=false               # Enable voice integration
ENABLE_WHATSAPP=true                 # Enable WhatsApp channel
ENABLE_EMAIL_CHANNEL=true            # Enable email channel
ENABLE_SMS_CHANNEL=true              # Enable SMS channel

Database Configuration

The system uses Prisma ORM. Schema is in backend/prisma/schema.prisma. Common commands:

# Generate Prisma client
npm run prisma:generate

# Create migration
npm run prisma:migrate:create

# Apply migrations
npm run prisma:migrate:deploy

# Open Prisma Studio (GUI for database)
npm run prisma:studio

# Reset database (WARNING: Deletes all data)
npm run prisma:reset

Stripe Configuration

1. Create Products in Stripe Dashboard

Navigate to Products and create:

Free Tier - $0.00/month
Basic Plan - $99.97/month
Premium Plan - $149.97/month
Overage Messaging - $0.015 per message (usage-based)

2. Configure Webhooks

Add webhook endpoint: https://your-domain.com/api/webhooks/stripe Select events:

checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.payment_succeeded
invoice.payment_failed

3. Test Mode

During development, use Stripe test mode:

Test card: 4242 4242 4242 4242
Any future expiry date
Any 3-digit CVC

Twilio Configuration

1. Purchase Phone Numbers

Buy a phone number with SMS capability
Buy a phone number with WhatsApp capability (optional)

2. Configure Webhooks

Set SMS webhook to: https://your-domain.com/api/webhooks/twilio/sms Set WhatsApp webhook to: https://your-domain.com/api/webhooks/twilio/whatsapp

3. Messaging Service

Create a Messaging Service in Twilio for better deliverability.

💻 Development

Project Structure

funnelchat/
├── backend/                      # Backend application
│   ├── src/
│   │   ├── api/                  # API routes
│   │   │   ├── routes/           # Express routes
│   │   │   ├── controllers/      # Request handlers
│   │   │   ├── middlewares/      # Express middlewares
│   │   │   └── validators/       # Request validators
│   │   ├── services/             # Business logic
│   │   │   ├── chatbot/          # AI chatbot service
│   │   │   ├── payment/          # Payment processing
│   │   │   ├── analytics/        # Analytics engine
│   │   │   ├── compliance/       # Compliance checker
│   │   │   └── notification/     # Multi-channel notifications
│   │   ├── integrations/         # Third-party integrations
│   │   │   ├── anthropic/        # Claude AI client
│   │   │   ├── stripe/           # Stripe client
│   │   │   ├── twilio/           # Twilio client
│   │   │   └── sendgrid/         # SendGrid client
│   │   ├── database/             # Database layer
│   │   │   ├── repositories/     # Data access layer
│   │   │   └── models/           # Data models
│   │   ├── utils/                # Utility functions
│   │   ├── config/               # Configuration files
│   │   └── types/                # TypeScript types
│   ├── prisma/
│   │   ├── schema.prisma         # Database schema
│   │   ├── migrations/           # Database migrations
│   │   └── seed.ts               # Database seeder
│   ├── tests/                    # Test files
│   │   ├── unit/                 # Unit tests
│   │   ├── integration/          # Integration tests
│   │   └── e2e/                  # End-to-end tests
│   └── package.json
│
├── frontend/
│   ├── debtor-portal/            # Public debtor interface
│   │   ├── src/
│   │   │   ├── components/       # React components
│   │   │   ├── pages/            # Page components
│   │   │   ├── hooks/            # Custom React hooks
│   │   │   ├── store/            # Redux store
│   │   │   ├── services/         # API clients
│   │   │   ├── utils/            # Utilities
│   │   │   └── types/            # TypeScript types
│   │   └── package.json
│   │
│   ├── business-dashboard/       # Business user interface
│   │   └── [similar structure]
│   │
│   └── admin-panel/              # Admin interface
│       └── [similar structure]
│
├── shared/                       # Shared code
│   ├── types/                    # Shared TypeScript types
│   └── constants/                # Shared constants
│
├── docker-compose.yml            # Docker orchestration
├── .env.example                  # Environment template
└── README.md                     # This file

Coding Standards

TypeScript

Use strict mode: "strict": true in tsconfig.json
Avoid any type; use proper typing
Use interfaces for object shapes
Use enums for fixed sets of values

Example:

// Good ✅
interface User {
  id: string;
  email: string;
  role: UserRole;
}

enum UserRole {
  ADMIN = 'admin',
  AGENT = 'agent',
  DEBTOR = 'debtor'
}

// Bad ❌
const user: any = {...}

Naming Conventions

Files: kebab-case (e.g., payment-service.ts)
Classes: PascalCase (e.g., PaymentService)
Functions: camelCase (e.g., calculatePaymentPlan)
Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRY_ATTEMPTS)
Components: PascalCase (e.g., ChatWidget.tsx)

Code Organization

One component per file
Keep functions small (< 50 lines)
Extract reusable logic into hooks or utils
Comment complex logic

Git Workflow

# Create feature branch
git checkout -b feature/payment-plan-ui

# Make changes and commit
git add .
git commit -m "feat: add payment plan negotiation UI"

# Push and create pull request
git push origin feature/payment-plan-ui

Commit message format:

feat: - New feature
fix: - Bug fix
docs: - Documentation
style: - Code style changes
refactor: - Code refactoring
test: - Adding tests
chore: - Maintenance tasks

Development Workflow

1. Start Development Environment

docker-compose up -d

2. Watch for File Changes

Backend and frontend will auto-reload on file changes when using npm run dev or npm start.

3. View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api

4. Access Database

# Prisma Studio (GUI)
npm run prisma:studio

# PostgreSQL CLI
docker-compose exec postgres psql -U funnelchat_user funnelchat_dev

5. Test API Endpoints

Use Postman collection in docs/postman/ or:

# Health check
curl http://localhost:4000/health

# Login
curl -X POST http://localhost:4000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@funnelchat.com","password":"admin123"}'

Common Development Tasks

Add a New API Endpoint

Create route in backend/src/api/routes/:

// backend/src/api/routes/accounts.ts
import express from 'express';
import { getAccount } from '../controllers/accounts';
import { authenticate } from '../middlewares/auth';

const router = express.Router();

router.get('/:id', authenticate, getAccount);

export default router;

Create controller in backend/src/api/controllers/:

// backend/src/api/controllers/accounts.ts
import { Request, Response } from 'express';
import { AccountService } from '../../services/account-service';

export async function getAccount(req: Request, res: Response) {
  try {
    const account = await AccountService.getById(req.params.id);
    res.json(account);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

Register route in backend/src/api/index.ts:

import accountsRouter from './routes/accounts';
app.use('/api/accounts', accountsRouter);

Add a New React Component

Create component file:

// frontend/debtor-portal/src/components/PaymentButton.tsx
import React from 'react';
import { Button } from '@mui/material';

interface PaymentButtonProps {
  amount: number;
  onPayment: () => void;
}

export const PaymentButton: React.FC<PaymentButtonProps> = ({ 
  amount, 
  onPayment 
}) => {
  return (
    <Button 
      variant="contained" 
      color="primary"
      onClick={onPayment}
    >
      Pay ${amount}
    </Button>
  );
};

Use in parent component:

import { PaymentButton } from '../components/PaymentButton';

<PaymentButton 
  amount={100} 
  onPayment={() => console.log('Payment clicked')} 
/>

Add a Database Table

Update Prisma schema:

// backend/prisma/schema.prisma
model PaymentPlan {
  id              String   @id @default(uuid())
  debtorId        String
  totalAmount     Decimal  @db.Decimal(10, 2)
  installments    Int
  status          String
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
  
  debtor          Debtor   @relation(fields: [debtorId], references: [id])
}

Create migration:

npm run prisma:migrate:create --name add_payment_plans

Apply migration:

npm run prisma:migrate:deploy

🧪 Testing

Running Tests

Run all tests:

npm test

Run specific test suite:

npm test -- payment-service

Run with coverage:

npm run test:coverage

Watch mode (re-runs on file changes):

npm run test:watch

Test Structure

// backend/tests/unit/services/payment-service.test.ts
import { PaymentService } from '../../../src/services/payment-service';

describe('PaymentService', () => {
  describe('calculatePaymentPlan', () => {
    it('should calculate monthly payments correctly', () => {
      const plan = PaymentService.calculatePaymentPlan({
        totalAmount: 1200,
        months: 12
      });
      
      expect(plan.monthlyPayment).toBe(100);
      expect(plan.installments).toBe(12);
    });
    
    it('should throw error for invalid amounts', () => {
      expect(() => {
        PaymentService.calculatePaymentPlan({
          totalAmount: -100,
          months: 12
        });
      }).toThrow('Amount must be positive');
    });
  });
});

E2E Testing

E2E tests use Playwright or Cypress:

# Install Playwright
npm install -D @playwright/test

# Run E2E tests
npm run test:e2e

Example E2E test:

// tests/e2e/payment-flow.spec.ts
import { test, expect } from '@playwright/test';

test('complete payment flow', async ({ page }) => {
  await page.goto('http://localhost:3000');
  
  // Login
  await page.fill('[name="email"]', 'debtor@example.com');
  await page.fill('[name="password"]', 'password123');
  await page.click('button[type="submit"]');
  
  // Make payment
  await page.click('text=Make Payment');
  await page.fill('[name="amount"]', '100');
  await page.click('button:has-text("Pay Now")');
  
  // Verify success
  await expect(page.locator('text=Payment Successful')).toBeVisible();
});

🚢 Deployment

Environment Setup

Create separate environments:

Development - Local machine
Staging - Pre-production testing
Production - Live system

Deployment Checklist

Before deploying to production:

Docker Deployment

Build production images:

docker build -t funnelchat-api:latest -f backend/Dockerfile.prod .
docker build -t funnelchat-debtor:latest -f frontend/debtor-portal/Dockerfile.prod .
docker build -t funnelchat-business:latest -f frontend/business-dashboard/Dockerfile.prod .
docker build -t funnelchat-admin:latest -f frontend/admin-panel/Dockerfile.prod .

Push to registry:

docker tag funnelchat-api:latest your-registry.com/funnelchat-api:latest
docker push your-registry.com/funnelchat-api:latest

Cloud Deployment Options

AWS (Recommended)

Compute: ECS or EKS for containers
Database: RDS for PostgreSQL
Cache: ElastiCache for Redis
Storage: S3 for files
CDN: CloudFront

DigitalOcean (Budget-Friendly)

Compute: App Platform or Droplets
Database: Managed PostgreSQL
Cache: Managed Redis
Storage: Spaces (S3-compatible)

Render (Easiest for Beginners)

Web Services: Auto-deploy from Git
Databases: Managed PostgreSQL
Redis: Managed Redis
Static Sites: Auto-deploy frontends

Continuous Deployment

GitHub Actions example:

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run Tests
        run: |
          npm install
          npm test
      
      - name: Build Docker Images
        run: docker-compose build
      
      - name: Push to Registry
        run: |
          docker push your-registry.com/funnelchat-api:latest
      
      - name: Deploy to Production
        run: |
          # Your deployment script

Database Migrations in Production

Safe migration process:

Backup database:

pg_dump -U funnelchat_user funnelchat_prod > backup.sql

Test migration on staging:

npm run prisma:migrate:deploy

Deploy to production:

# SSH into production server
npm run prisma:migrate:deploy

Verify application:

curl https://api.funnelchat.com/health

Monitoring

Set up monitoring for:

Application health: Uptime checks
API performance: Response times
Error rates: Exception tracking
Database performance: Query times
Message delivery: Channel success rates

Tools:

Datadog
New Relic
Sentry (error tracking)
CloudWatch (AWS)

📚 API Documentation

Authentication

All API requests require authentication via JWT token. Get token:

POST /api/auth/login
{
  "email": "user@example.com",
  "password": "password123"
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { ... }
}

Use token:

GET /api/accounts
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Key Endpoints

Full API documentation available at: http://localhost:4000/api-docs (Swagger UI) Core endpoints:

POST /api/auth/login - User login
POST /api/auth/register - User registration
GET /api/accounts - List accounts
GET /api/accounts/:id - Get account details
POST /api/conversations - Start conversation
POST /api/payments - Process payment
GET /api/analytics/dashboard - Get dashboard data

WebSocket Events

Real-time communication uses Socket.io. Client connection:

import io from 'socket.io-client';

const socket = io('http://localhost:4000', {
  auth: {
    token: 'your-jwt-token'
  }
});

// Listen for messages
socket.on('message', (data) => {
  console.log('New message:', data);
});

// Send message
socket.emit('send_message', {
  conversationId: '123',
  content: 'Hello'
});

Events:

message - New chat message
typing - User is typing
payment_update - Payment status change
conversation_assigned - Conversation assigned to agent

🤝 Contributing

We welcome contributions! Please follow these guidelines.

Getting Started

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Write/update tests
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Pull Request Process

Update documentation if you changed APIs or behavior
Add tests for new functionality
Ensure all tests pass: npm test
Follow code style: npm run lint
Update CHANGELOG.md with your changes
Request review from maintainers

Code Review Criteria

Code follows project conventions
Adequate test coverage (>80%)
No security vulnerabilities
Performance considerations addressed
Documentation updated
Commit messages are clear

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Getting Help

Documentation: Check this README and PRD
Issues: Create GitHub issue with bug/feature tag
Discussions: Use GitHub Discussions for questions
Email: support@funnelchat.com

Common Issues

Issue: Cannot connect to database

Solution: 
Check PostgreSQL is running: `docker-compose ps`
Verify DATABASE_URL in .env
Check credentials and database exists

Issue: API returns 401 Unauthorized

Solution:
Check JWT token is included in Authorization header
Verify token hasn't expired
Check JWT_SECRET matches between frontend and backend

Issue: Chatbot not responding

Solution:
Verify ANTHROPIC_API_KEY is set correctly
Check API quota hasn't been exceeded
Review logs: `docker-compose logs api`

Troubleshooting Commands

# View all running containers
docker-compose ps

# View logs
docker-compose logs -f api

# Restart specific service
docker-compose restart api

# Rebuild containers
docker-compose up -d --build

# Reset everything (WARNING: deletes data)
docker-compose down -v
docker-compose up -d
npm run prisma:reset

📞 Contact

Project Lead: Oxford Pierpont
Organization: aiConnected
Website: https://funnelchat.com
GitHub: https://github.com/your-org/funnelchat

Happy Coding! 🚀

Project Requirements Document (PRD)funnelChat AI Powered Debt Collection Platform Version : 1.0 Date : November 23, 2025 Author : Oxford Pierpont / aiConnected Status : Ready for Development T...

​funnelChat by aiConnected

​📋 Table of Contents

​🎯 Overview

​What Does This Platform Do?

​✨ Features

​Core Features

​1. Multi-Channel Communication

​2. AI-Powered Conversations

​3. Payment Management

​4. Compliance & Security

​5. Analytics & Reporting

​🏗️ Architecture

​High-Level Architecture

​System Components

​Front-End Applications

​Back-End Services

​🛠️ Tech Stack

​Front-End

​Back-End

​Database

​AI & NLP

​Third-Party Integrations

​Infrastructure

​Development Tools

​📦 Prerequisites

​Required Software

​Required API Keys

​Development Skills

​🚀 Installation

​Option 1: Docker Setup (Recommended for Beginners)

​Option 2: Manual Setup

​Step 1: Clone Repository

​Step 2: Install Dependencies

​Step 3: Setup Database

​Step 4: Configure Environment Variables

​Step 5: Run Database Migrations

​Step 6: Seed Database (Optional)

​Step 7: Start Development Servers

​⚙️ Configuration

​Environment Variables Explained

​Critical Security Settings

​API Keys

​Feature Flags

​Database Configuration

​Stripe Configuration

​1. Create Products in Stripe Dashboard

​2. Configure Webhooks

​3. Test Mode

​Twilio Configuration

​1. Purchase Phone Numbers

​2. Configure Webhooks

​3. Messaging Service

​💻 Development

​Project Structure

​Coding Standards

​TypeScript

​Naming Conventions

​Code Organization

​Git Workflow

​Development Workflow

​1. Start Development Environment

​2. Watch for File Changes

​3. View Logs

​4. Access Database

​5. Test API Endpoints

​Common Development Tasks

​Add a New API Endpoint

​Add a New React Component

​Add a Database Table

​🧪 Testing

​Running Tests

​Test Structure

​E2E Testing

​🚢 Deployment

​Environment Setup

​Deployment Checklist

​Docker Deployment

​Cloud Deployment Options

​AWS (Recommended)

​DigitalOcean (Budget-Friendly)

funnelChat by aiConnected

📋 Table of Contents

🎯 Overview

What Does This Platform Do?

✨ Features

Core Features

1. Multi-Channel Communication

2. AI-Powered Conversations

3. Payment Management

4. Compliance & Security

5. Analytics & Reporting

🏗️ Architecture

High-Level Architecture

System Components

Front-End Applications

Back-End Services

🛠️ Tech Stack

Front-End

Back-End

Database

AI & NLP

Third-Party Integrations

Infrastructure

Development Tools

📦 Prerequisites

Required Software

Required API Keys

Development Skills

🚀 Installation

Option 1: Docker Setup (Recommended for Beginners)

Option 2: Manual Setup

Step 1: Clone Repository

Step 2: Install Dependencies

Step 3: Setup Database

Step 4: Configure Environment Variables

Step 5: Run Database Migrations

Step 6: Seed Database (Optional)

Step 7: Start Development Servers

⚙️ Configuration

Environment Variables Explained

Critical Security Settings

API Keys

Feature Flags

Database Configuration

Stripe Configuration

1. Create Products in Stripe Dashboard

2. Configure Webhooks

3. Test Mode

Twilio Configuration

1. Purchase Phone Numbers

2. Configure Webhooks

3. Messaging Service

💻 Development

Project Structure

Coding Standards

TypeScript

Naming Conventions

Code Organization

Git Workflow

Development Workflow

1. Start Development Environment

2. Watch for File Changes

3. View Logs

4. Access Database

5. Test API Endpoints

Common Development Tasks

Add a New API Endpoint

Add a New React Component

Add a Database Table

🧪 Testing

Running Tests

Test Structure

E2E Testing

🚢 Deployment

Environment Setup

Deployment Checklist

Docker Deployment

Cloud Deployment Options

AWS (Recommended)

DigitalOcean (Budget-Friendly)