AI Lead Qualifier

AI Lead Qualifier is a portfolio project that simulates an AI-powered lead qualification workflow for sales teams.

The backend receives lead data, analyzes the business need, and returns:

• qualification status
• lead score
• business reason for the decision
• suggested outreach message

The project now also includes a simple React frontend so the flow can be tested through a web interface.

Demo Flow

1. The user fills in the company name and lead need.
2. The React frontend sends the data to the API.
3. The backend processes the lead with either:
   • a local mock service
   • the OpenAI API
4. The application returns a structured result for display.

Features

• Lead qualification through a REST API
• Validation for required input fields
• Qualification result with status, score, reason, and suggestedApproach
• Support for mock and openai provider modes
• React frontend for manual testing and presentation
• Vite proxy setup for local frontend-to-backend communication

Tech Stack

• Node.js
• Express
• JavaScript
• dotenv
• OpenAI API
• React
• Vite

Project Structure

.
|-- src/
|   |-- config/
|   |   `-- env.js
|   |-- prompts/
|   |   `-- leadQualificationPrompt.js
|   |-- services/
|   |   |-- aiService.js
|   |   |-- mockAiService.js
|   |   `-- openaiAiService.js
|   |-- app.js
|   |-- index.js
|   `-- server.js
|-- frontend/
|   |-- src/
|   |   |-- App.jsx
|   |   |-- main.jsx
|   |   `-- styles.css
|   |-- index.html
|   |-- package.json
|   `-- vite.config.js
|-- .env.example
|-- package.json
`-- README.md

Environment Variables

Create a .env file based on .env.example.

Example:

AI_PROVIDER=mock
OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.4-mini
PORT=3000

Providers

• AI_PROVIDER=mock: uses the local simulated qualification logic
• AI_PROVIDER=openai: uses the OpenAI API when OPENAI_API_KEY is present

Installation

Clone the repository:

git clone https://github.com/your-username/ai-lead-qualifier.git
cd ai-lead-qualifier

Install backend dependencies:

npm install

Install frontend dependencies:

cd frontend
npm install
cd ..

Running the Project

Backend

Start the API server:

npm run dev

The backend runs on:

http://localhost:3000

Frontend

Start the React app:

cd frontend
npm run dev

The frontend runs on:

http://localhost:5173

The Vite dev server proxies API requests to http://localhost:3000.

API Endpoints

GET /

Returns a simple status message.

Example response:

AI Lead Qualifier API is running.

GET /health

Returns the application health status.

Example response:

{
  "status": "ok"
}

GET /test-lead

Quick browser-friendly route for testing lead qualification.

Example:

/test-lead?company=LojaMax&need=We%20need%20to%20automate%20lead%20qualification

Example response:

{
  "companyName": "LojaMax",
  "needDescription": "We need to automate lead qualification",
  "status": "qualified",
  "score": 95,
  "reason": "The lead shows a clear business need related to sales efficiency, automation, or lead qualification, which suggests a relevant commercial opportunity.",
  "suggestedApproach": "Hi LojaMax, I noticed your team is looking to improve lead qualification and sales efficiency. We can help with an AI solution to automate triage, prioritize opportunities, and improve conversion.",
  "source": "mock"
}

POST /qualify-lead

Qualifies a lead from a JSON request body.

Example request:

{
  "companyName": "ClinicFlow",
  "needDescription": "We need an AI workflow to filter inbound leads and prioritize high-intent contacts."
}

Example response:

{
  "companyName": "ClinicFlow",
  "needDescription": "We need an AI workflow to filter inbound leads and prioritize high-intent contacts.",
  "status": "qualified",
  "score": 80,
  "reason": "The lead shows a clear business need related to sales efficiency, automation, or lead qualification, which suggests a relevant commercial opportunity.",
  "suggestedApproach": "Hi ClinicFlow, I noticed your team is looking to improve lead qualification and sales efficiency. We can help with an AI solution to automate triage, prioritize opportunities, and improve conversion.",
  "source": "mock"
}

Frontend Overview

The React frontend lives in frontend/ and provides:

• a form to enter lead data
• a demo button to quickly preload example content
• a result panel with qualification status, score, reason, and suggested approach
• a direct link to the API health route

Error Handling

The API validates input before trying to process the lead.

Example invalid request:

{
  "companyName": "",
  "needDescription": "short"
}

Example response:

{
  "error": "Invalid input. Please provide a valid company name and a more detailed need description."
}

Why This Project Matters

This project demonstrates a realistic AI use case for sales operations:

• lead triage
• lead qualification
• opportunity analysis
• suggested commercial outreach
• architecture ready for future CRM integration

Future Improvements

• Integrate with CRM platforms
• Persist lead history in a database
• Add authentication
• Add analytics and reporting
• Improve qualification criteria
• Add logging and observability
• Deploy with production monitoring

Learning Goals Demonstrated

• Express API development
• modular project structure
• environment configuration
• provider abstraction for AI services
• prompt construction
• graceful fallback from OpenAI to mock mode
• structured JSON responses
• React integration with an existing backend

Author

Developed by Mayson Lima dos Santos as a portfolio project focused on backend development and practical AI applications.