Prowider — Professional Lead Distribution System

A production-ready lead generation and intelligent distribution platform built with modern web technologies. Prowider uses a fair, efficient allocation algorithm to distribute customer leads to service providers while respecting monthly quotas.

View Live Demo • GitHub Issues • Report Bug

✨ Features

🚀 Real-time Dashboard — Live provider metrics with Server-Sent Events (SSE)
⚖️ Fair Lead Allocation — Intelligent round-robin algorithm with quota management
🔒 Concurrency-Safe — Serializable database transactions prevent race conditions
📞 Customer Forms — Easy lead submission with service selection
🔌 Webhook Support — Idempotent quota reset via webhooks
📊 Provider Analytics — Track leads, quota usage, and performance
🛠️ Admin Tools — Built-in testing suite and load generation
🎨 Responsive UI — Mobile-friendly design with Tailwind CSS

🏗️ Architecture

Tech Stack

Layer	Technology	Version	Purpose
Frontend	Next.js (App Router)	16.2	UI, routing, SSE streaming
Backend	Node.js + Express	Built-in	API routes and business logic
Database	PostgreSQL	Latest	Persistent data storage
ORM	Prisma	7.8	Type-safe database access
Real-time	Server-Sent Events	Native	Live dashboard updates
Styling	Tailwind CSS	4	Utility-first CSS framework
Validation	Zod	4.4	Type-safe schema validation

Data Model

Service (service, id, name) 
  ├── Lead (customer inquiry with phone, name, city, description)
  │   └── LeadAssignment (assigned to 3 providers per lead)
  ├── Provider (8 providers, each with monthly quota of 10 leads)
  └── AllocationState (tracks round-robin pointer per service)

WebhookEvent (idempotency keys for quota resets)

🚀 Quick Start

Prerequisites

Node.js 18+ or 20+
npm or yarn
PostgreSQL 12+
Git

Installation

# 1. Clone the repository
git clone https://github.com/Shree-svg/Prowider.git
cd Prowider

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.local.example .env.local

# Edit .env.local and add your PostgreSQL connection string:
# DATABASE_URL="postgresql://user:password@localhost:5432/prowider"

Database Setup

# 1. Create database schema
npx prisma db push

# 2. Seed with demo data (3 services, 8 providers, allocation state)
npx prisma db seed

# 3. (Optional) Generate Prisma client after schema changes
npx prisma generate

Running the Application

# Development mode (hot reload enabled)
npm run dev

# Production build
npm run build

# Start production server
npm start

# The application will be available at http://localhost:3000

Database Migrations

# Deploy pending migrations (production)
npm run db:migrate

# View Prisma Studio (interactive database explorer)
npx prisma studio

📍 Routes & Pages

URL Path	Purpose	Access
`/`	Home page with navigation	Public
`/request-service`	Customer lead submission form	Public
`/dashboard`	Real-time provider dashboard & analytics	Public*
`/test-tools`	Webhook testing & load generation	Development

*Dashboard displays real-time lead allocations and provider quotas via SSE.

🎯 Core Features

1. Intelligent Lead Allocation

Prowider implements a sophisticated allocation algorithm that:

Assigns exactly 3 providers per lead to maximize reach
Guarantees mandatory assignments for critical providers
Uses persistent round-robin to fairly distribute remaining slots
Respects monthly quotas (default: 10 leads/provider)
Survives server restarts via database-backed state

Example Allocation Rules

Service	Mandatory Providers	Round-Robin Pool
Service 1	Provider 1	[2, 3, 4]
Service 2	Provider 5	[6, 7, 8]
Service 3	Providers 1, 4	[2, 3, 5, 6, 7, 8]

2. Concurrency & Consistency

✅ Serializable Transactions — Highest isolation level prevents anomalies
✅ Row-Level Locking — SELECT … FOR UPDATE ensures atomic state updates
✅ Distributed-Safe — Works correctly across multiple server instances
✅ No In-Memory Locks — All synchronization at database level

3. Duplicate Prevention

Database Constraint — UNIQUE(phone, serviceId) on Lead table
API Response — Returns 409 Conflict with clear error message
Enforced at DB Level — Not just application logic

4. Webhook Idempotency

Quota resets via webhooks are idempotent:

POST /api/webhook
{
  "idempotencyKey": "unique-key-12345",
  "action": "reset_quota",
  "providerId": 1
}

✅ Same key: Returns 200 with idempotent: true, no quota reset
✅ New key: Processes quota reset, records key in database
✅ Race-condition safe: Key recording happens in same transaction

🔧 API Endpoints

Leads

# Create a new lead
POST /api/leads
Content-Type: application/json

{
  "name": "John Doe",
  "phone": "+1234567890",
  "city": "New York",
  "description": "Need business consultation",
  "serviceId": 1
}

# Response (Success): 201 Created
{
  "success": true,
  "leadId": 42,
  "providers": [1, 3, 5]
}

# Response (Duplicate): 409 Conflict
{
  "error": "Lead already exists for this phone and service"
}

Providers

# Get all providers
GET /api/providers

# Response: 200 OK
{
  "providers": [
    { "id": 1, "name": "Provider A", "monthlyQuota": 10, "leadsCount": 7 },
    { "id": 2, "name": "Provider B", "monthlyQuota": 10, "leadsCount": 5 },
    ...
  ]
}

Services

# Get all services
GET /api/services

# Response: 200 OK
{
  "services": [
    { "id": 1, "name": "Business Consultation" },
    { "id": 2, "name": "Legal Services" },
    { "id": 3, "name": "Tax Planning" }
  ]
}

Real-time Updates

# Server-Sent Events stream
GET /api/sse

# Pushes updates when leads are created:
data: {
  "type": "lead_created",
  "lead": { "id": 42, "name": "John Doe", "providers": [1, 3, 5] },
  "timestamp": "2024-05-18T10:30:00Z"
}

Webhook Quota Reset

POST /api/webhook
Content-Type: application/json

{
  "idempotencyKey": "reset-provider-1-2024-05",
  "action": "reset_quota",
  "providerId": 1
}

# Response: 200 OK
{
  "success": true,
  "idempotent": false,
  "message": "Provider 1 quota reset to 0"
}

📊 Testing & Development

Testing Tools

Access the internal testing suite at /test-tools:

Manual Lead Creation — Create leads with custom data
Load Testing — Generate bulk leads to test system capacity
Webhook Testing — Send test webhooks with custom payloads
Real-time Monitoring — Watch allocations happen live

Running Tests

# Lint the codebase (ESLint + Next.js rules)
npm run lint

# Generate TypeScript types
npm run db:generate

# Seed database with fresh demo data
npm run db:seed

# View database in Prisma Studio
npx prisma studio

🔐 Environment Variables

Create a .env.local file:

# Required: PostgreSQL connection string
DATABASE_URL="postgresql://user:password@localhost:5432/prowider"

# Optional: Enable debug logging (development only)
DEBUG=prowider:*

# Optional: Node environment
NODE_ENV=development  # or production

📈 Production Deployment

Deploy to Vercel

# 1. Push code to GitHub
git push origin main

# 2. Connect repository to Vercel
# Visit: https://vercel.com/new

# 3. Set environment variables in Vercel dashboard
# - DATABASE_URL: Your production PostgreSQL URL

# 4. Vercel auto-deploys on push

Deploy to Railway, Render, or Self-Hosted

Similar process — ensure DATABASE_URL is set and run migrations:

npm run db:migrate  # Deploy schema changes
npm run build       # Build Next.js app
npm start          # Start server

🛠️ Development

Project Structure

Prowider/
├── app/                    # Next.js app router
│   ├── api/               # API routes
│   │   ├── leads/        # Lead creation
│   │   ├── providers/    # Provider data
│   │   ├── services/     # Service data
│   │   ├── sse/          # Server-Sent Events
│   │   ├── webhook/      # Webhook handler
│   │   └── test/         # Testing endpoints
│   ├── dashboard/        # Real-time dashboard UI
│   ├── request-service/  # Customer form page
│   ├── test-tools/       # Testing UI
│   └── layout.tsx        # Root layout
├── lib/                   # Utility functions
├── prisma/
│   ├── schema.prisma     # Database schema
│   └── seed.ts           # Database seed script
├── public/               # Static assets
├── tailwind.config.mjs   # Tailwind configuration
├── tsconfig.json         # TypeScript configuration
└── next.config.ts        # Next.js configuration

Code Style

TypeScript — Strict mode enabled
ESLint — Next.js recommended rules
Formatting — Prettier compatible
Tailwind — Utility-first CSS

Run linter:

npm run lint

🚨 Design Highlights

Why Serializable + Row Locks?

Problem: Multiple servers allocating leads concurrently might skip providers.

Solution:

Serializable isolation — Strongest database guarantee
SELECT … FOR UPDATE — Locks AllocationState row during transaction
Result — Concurrent requests queue naturally; no race conditions

Why Database-Backed Idempotency?

Problem: Retried webhooks could double-reset quotas.

Solution:

Check idempotencyKey in WebhookEvent table first
If exists: Return 200 immediately (idempotent)
If new: Process reset + record key in same transaction
Result — Transactionally safe; no race window

📝 License

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

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Guidelines

Write TypeScript (no any types)
Follow ESLint rules
Add comments for complex logic
Test changes locally before pushing

🐛 Issues & Feedback

Found a bug or have a suggestion?

Report Bug: GitHub Issues
Feature Request: GitHub Discussions
Security: Please don't open public issues for security vulnerabilities

📞 Support

For questions or issues:

Check the Troubleshooting section
Review API Endpoints documentation
Open an issue on GitHub
Check existing GitHub issues for similar problems

Troubleshooting

Q: Database connection fails
A: Verify DATABASE_URL is correct and PostgreSQL server is running.

Q: npm run db:seed fails
A: Run npx prisma db push first to create schema.

Q: Real-time dashboard not updating
A: Ensure Server-Sent Events (SSE) is not blocked by proxies/firewalls.

Q: Build fails with TypeScript errors
A: Run npm run db:generate to regenerate Prisma types.

🙏 Acknowledgments

Built with Next.js and TypeScript
Database powered by PostgreSQL and Prisma
Styled with Tailwind CSS
Deployed on Vercel

📜 Version History

v0.1.0 (Current) — Initial release with core lead distribution, real-time dashboard, and webhook support

⬆ Back to Top

Made with ❤️ by Shree-svg

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
app		app
lib		lib
prisma		prisma
public		public
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
prisma.config.ts		prisma.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation