ScoreStream: Event-Driven Lead Scoring System 🚀

ScoreStream is a real-time, scalable application designed to evaluate and rank sales leads based on their interactions. Built with an Event-Driven Architecture, it ensures high performance, idempotency, and immediate feedback via WebSockets.

🌟 Key Features

• Event-Driven Core: Decoupled processing using BullMQ and Redis.
• Real-Time Updates: Live score changes pushed to the frontend via Socket.IO.
• Dynamic Scoring Rules: Configure points for events (e.g., Email Open = +5, Purchase = +100) on the fly.
• Idempotency & Ordering: Guarantees unique event processing and handles out-of-order delivery.
• Score Cap & Decay: Implements a hard score cap (1000) and automatic time-based decay for inactive leads (Bonus).
• Analytics: Visual score trends, full event audit history, and CSV export.

🛠️ Tech Stack

• Backend: Node.js, Express.js
• Database: MongoDB (Mongoose)
• Queue System: BullMQ, Redis
• Real-Time: Socket.IO
• Frontend: React, Vite, Recharts, CSS Modules (Glassmorphism UI)
• Testing: Jest, Supertest

🚀 Getting Started

Prerequisites

• Node.js (v16+)
• MongoDB (Running locally on 27017)
• Redis (Running locally on 6379)

Installation

1. Clone the repository

   git clone https://github.com/Archisman-NC/ScoreStream.git
   cd ScoreStream

2. Backend Setup

   cd backend
   npm install
   # Create .env (Optional, defaults provided in code)
   # PORT=5001
   # MONGO_URI=mongodb://localhost:27017/scorestream
   # REDIS_HOST=localhost
   
   # Start Server (Development)
   npm run dev

3. Frontend Setup

   cd ../frontend
   npm install
   npm run dev

4. Access the App Open http://localhost:5173 in your browser.

🧪 Running Tests

The project includes a comprehensive Unit and Integration test suite.

cd backend
npm test

📚 API Overview

Method	Endpoint	Description
POST	/api/events/manual	Submit a single event (Real-time).
POST	/api/events/webhook	High-throughput webhook ingestion.
POST	/api/events/batch	Upload CSV/JSON batch files.
GET	/api/leads	Retrieve all leads.
GET	/api/leads/leaderboard	Get top leads sorted by score.
PUT	/api/scoring-rules	Update scoring logic.
GET	/api/utils/export/leads	Download Leads CSV.

💎 Bonus Features Implemented

1. Score Decay: A background worker runs every minute to deduct points from inactive leads.
2. CSV Export: One-click data export from the Dashboard.
3. Negative Scores: Fully supported in the scoring rules engine.

📄 License

This project is licensed under the MIT License.