# Lead Workflow Automation System

A **modular, data-driven workflow engine** built with **NestJS + TypeORM** that qualifies leads through configurable stages (validation, scoring, communication, …).  
Extensible via the **Strategy + Factory** pattern – new stage types can be added without touching core logic.

---

## Features
- **Lead CRUD** (`POST /leads`, `GET /leads/:id`, …)  
- **Dynamic workflow definition** stored in PostgreSQL (`jsonb`)  
- **Asynchronous execution** with full stage history (`stage_executions`)  
- **Pass / Fail transitions** (`nextOnPass`, `nextOnFail`)  
- **Seed script** for instant demo data  

---

## Tech Stack
| Layer | Technology |
|-------|------------|
| Backend | NestJS 10, TypeORM, PostgreSQL |
| Validation | class-validator |
| API Docs | Swagger (`/api/docs`) |
| Health Check | `/api/health` |

---

## Demo docs bidoe 
(https://www.awesomescreenshot.com/video/45746826?key=3f06db38a2c48fae33ba90b73b97ad23)

## Quick Start (Yarn)

```bash
# 1. Clone & install
git clone https://github.com/devshakilh/lead-workflow-backend
cd lead-workflow-backend
yarn

# 2. Environment (.env)
cp .env.example .env
# edit DB credentials if needed
# 3. Run migrations & seed
yarn migration:run
yarn seed

# 4. Run dev server
yarn start:dev

API base: http://localhost:3000/api
Swagger UI: http://localhost:3000/api/docs
Health Check: http://localhost:3000/api/health

---

Core Endpoints

Method	Path	Description
POST	/leads	Create a lead
GET	/leads	List leads
GET	/workflows	List workflows
POST	/workflow-executions/start	Start workflow for a lead
GET	/workflow-executions/:id	Execution details + stage history

---

Architecture Highlights

WorkflowEngineService
   └─ StrategyFactory → ValidationStrategy | ScoringStrategy | CommunicationStrategy

• Configuration-driven – stages, rules, thresholds live in DB.
• Strategy Pattern – each stage is an injectable class implementing StageStrategy.
• Factory – resolves type → concrete strategy at runtime.

---

Adding a New Stage (Example: SMS)

1. Create strategy

   @Injectable()
   export class SmsStrategy implements StageStrategy {
     async execute(lead: Lead, config: any): Promise<StageResult> {
       // send SMS
       return { passed: true, data: { sent: true } };
     }
   }

2. Register in factory

   case 'sms': return this.smsStrategy;

3. Use in workflow JSON

   { "type": "sms", "nextOnPass": "Converted", "nextOnFail": "Rejected" }

No core engine changes required.

---

Database Schema (simplified)

leads                ← lead data + status/score
workflows            ← name + jsonb configuration
workflow_executions  ← leadId, workflowId, status, currentStage
stage_executions     ← executionId, stageName, result, durationMs

---

Scripts (Yarn)

Script	Purpose
yarn seed	Insert demo leads + 3 workflows
yarn migration:generate	Create TypeORM migration
yarn start:prod	Run compiled app

---

Future Extensions

• Manual Approval stage
• Webhook stage
• Retry policies