Coldi.ai Multi-Tenant Web Application

A production-ready multi-tenant web application for Coldi.ai that enables clients to test their Retell.ai bots with real voice calls, track call metrics, and manage billing with real-time updates.

Features

• Real Retell.ai Integration: Live voice calls using Retell.ai Web SDK
• Multi-tenant Architecture: Complete data isolation between client tenants
• User Authentication: JWT-based authentication with role-based access (admin/client)
• Bot Testing: Start real voice calls or simulated calls with live duration and cost tracking
• Real-time Metrics: WebSocket-powered live updates for calls and balances
• Admin Panel: Manage all tenants, view metrics, and adjust balances
• Billing System: Per-minute billing with minimum charge and balance tracking
• Modern UI: Tailwind CSS with glass-morphism design and animations

Prerequisites

• Node.js 18+
• MySQL 8.0+
• npm or yarn
• Retell.ai account with API key and agent IDs

Project Structure

├── backend/           # Express.js API server
│   ├── src/
│   │   ├── auth/      # Authentication module
│   │   ├── tenant/    # Tenant management
│   │   ├── call/      # Call handling with Retell integration
│   │   ├── billing/   # Billing logic
│   │   ├── admin/     # Admin routes
│   │   ├── retell/    # Retell.ai SDK integration
│   │   ├── websocket/ # Real-time updates
│   │   └── database/  # DB connection, migrations, seed
│   └── tests/         # Property-based tests
├── frontend/          # React + Vite + Tailwind client
│   └── src/
│       ├── components/
│       ├── contexts/
│       ├── hooks/
│       ├── pages/
│       └── services/
└── README.md

Environment Variables

Create a .env file in the backend/ directory:

# Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=coldi_db

# JWT Configuration
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=24h

# Server Configuration
PORT=3001

# Retell.ai Configuration (REQUIRED for real voice calls)
RETELL_API_KEY=key_your_retell_api_key

# Bot IDs (Retell.ai Agent IDs from your dashboard)
CLIENT_A_BOT_ID=agent_xxxxxxxxxxxxxxxx
CLIENT_B_BOT_ID=agent_yyyyyyyyyyyyyyyy

Retell.ai Setup

1. Create an account at Retell.ai
2. Get your API key from the dashboard
3. Create two agents (bots) for Client A and Client B
4. Copy the agent IDs to your .env file

Note: If Retell is not configured or the API key is invalid, the app will fall back to simulated calls (billing still works).

Database Setup

1. Create the Database

CREATE DATABASE coldi_db;

2. Run Migrations

cd backend
npm run migrate

3. Seed Demo Data

cd backend
npm run seed

This creates:

User	Email	Password	Role	Tenant
Admin	admin@coldi.ai	Admin123!	admin	-
Client A	a@client.local	ClientA123!	client	Client A
Client B	b@client.local	ClientB123!	client	Client B

Both tenants start with a $200.00 balance.

Running the Application

Backend

cd backend
npm install
npm run dev

The API server runs on http://localhost:3001

Frontend

cd frontend
npm install
npm run dev

The frontend runs on http://localhost:5173

API Endpoints

Method	Endpoint	Auth	Description
POST	/auth/login	None	Authenticate user
GET	/me	Required	Get current user profile
GET	/tenant/:tenantId/summary	Tenant/Admin	Get tenant metrics
GET	/tenant/:tenantId/bot	Tenant/Admin	Get tenant's bot ID
POST	/tenant/:tenantId/calls	Tenant/Admin	Start a new call (real or simulated)
POST	/tenant/:tenantId/calls/:id/end	Tenant/Admin	End an active call
GET	/tenant/:tenantId/calls	Tenant/Admin	List recent calls
GET	/admin/tenants	Admin	List all tenants
POST	/admin/tenants/:id/balance_adjustment	Admin	Adjust tenant balance
GET	/admin/tenants/:id/adjustments	Admin	Get balance adjustment history

Demo Steps

1. Login as Client A

1. Open http://localhost:5173
2. Login with a@client.local / ClientA123!
3. You'll see the modern dark-themed Client Dashboard

2. Make a Test Call

1. Click "Start Test Call"
2. If Retell is configured, you'll see "Live Voice" indicator and can speak with the AI
3. If not configured, the call runs in simulated mode (billing still works)
4. Watch the live duration timer and cost calculation
5. Click "End Call" to finish
6. Observe balance deducted and call in history

3. Login as Admin

1. Logout and login with admin@coldi.ai / Admin123!
2. View all tenants with their metrics
3. Click "Adjust" to modify a tenant's balance
4. Click "History" to view balance adjustment history

4. Verify Real-time Updates

1. Open two browser windows
2. Login as Client A in one, Admin in the other
3. Make a call or adjust balance
4. Both windows update in real-time via WebSocket

Billing Rules

• Rate: $0.40 per minute
• Minimum Charge: $0.40 for any call under 60 seconds
• Fractional Billing: Calls over 60 seconds are billed by exact duration
  • Example: 90 seconds = 1.5 minutes = $0.60
• Initial Balance: $200.00 per tenant
• Call Blocking: Tenants with negative balance cannot start new calls

Running Tests

cd backend
npm test

Property-based tests validate:

• Authentication correctness
• Tenant data isolation
• Cost calculation accuracy
• Balance deduction logic
• Metrics summary accuracy
• Call history ordering

Tech Stack

Backend:

• Express.js
• TypeScript
• MySQL2
• Socket.io
• JWT (jsonwebtoken)
• bcrypt
• Retell SDK

Frontend:

• React 18
• TypeScript
• Vite
• Tailwind CSS
• React Router
• Socket.io Client
• Axios
• Retell Client JS SDK

Testing:

• Vitest
• fast-check (property-based testing)

Production Deployment

1. Set secure JWT_SECRET in environment
2. Configure production MySQL database
3. Set valid Retell.ai API key and agent IDs
4. Build frontend: cd frontend && npm run build
5. Serve frontend static files
6. Run backend with PM2 or similar process manager