🧊 ICY - AI-Powered Influencer Outreach Platform

ICY is a comprehensive AI-powered platform that helps brands discover, analyze, and connect with relevant influencers across Instagram and YouTube. It leverages Google Gemini AI to provide intelligent insights, personalized outreach, and campaign management.

Features • Quick Start • Documentation • API Reference • Contributing

---

📋 Table of Contents

• Overview
• Features
• Technology Stack
• Project Structure
• Quick Start
• Configuration
• API Reference
• Frontend Features
• AI Capabilities
• Email Integration
• Testing
• Deployment
• Troubleshooting
• Documentation
• Contributing
• License

---

🌟 Overview

ICY (Influencer Connection Yield) is an end-to-end influencer marketing platform designed to streamline the entire influencer outreach workflow. From discovering the perfect influencers for your brand to sending personalized outreach campaigns and tracking performance analytics, ICY handles it all with the power of AI.

Key Highlights

• 🤖 AI-Powered Analysis - Leverages Google Gemini Pro for intelligent profile analysis and content generation
• 📊 Smart Matching - Advanced brand alignment scoring using keyword matching and niche analysis
• 📧 Automated Outreach - Bulk email campaigns with personalized messaging
• 📈 Campaign Analytics - Real-time tracking and performance insights
• 🔒 Secure Authentication - JWT-based authentication with session management
• ⚡ Performance Optimized - Built-in caching, rate limiting, and performance monitoring

---

✨ Features

🔍 Influencer Discovery

• Advanced Search - Filter influencers by platform, niche, follower count, engagement rate, and location
• Brand Alignment Scoring - AI-powered scoring based on keyword matching, follower ratios, and niche compatibility
• Bulk Analysis - Analyze multiple influencers simultaneously with detailed insights
• Real-time Dataset - Curated database of verified influencers with engagement metrics

🤖 AI-Powered Intelligence

Feature	Description
Profile Analysis	Deep-dive analysis of influencer authenticity, engagement quality, and audience demographics
Smart Outreach	Generate personalized messages tailored to each influencer's style and your brand voice
Content Ideas	Get creative content suggestions for influencer collaborations based on campaign goals
Authenticity Check	Detect fake followers, engagement manipulation, and assess profile credibility
Campaign Strategy	AI recommendations for budget allocation, timeline, and influencer selection
Image Analysis	Brand safety checking and visual content compliance using Gemini Vision

📧 Email Campaign Management

• Bulk Email Sending - Send personalized emails to multiple influencers with batch processing
• Rate Limiting - Built-in rate limiting to prevent email throttling (50 emails/minute)
• Delivery Tracking - Real-time tracking of email delivery status and analytics
• Email Templates - Create and manage reusable message templates with variables
• Campaign Logs - Detailed logs for debugging and audit purposes

📊 Analytics Dashboard

• Campaign Performance - Track response rates, conversions, and ROI metrics
• Influencer Insights - View historical performance data and engagement trends
• Brand Health Metrics - Monitor brand alignment scores across campaigns
• Export Reports - Generate detailed reports for stakeholders

🏢 Brand Profile Management

• Profile Setup - Configure your brand details, target audience, and preferences
• Niche Selection - Define your brand's categories and target influencer niches
• Content Guidelines - Set brand voice, tone, and content requirements
• Budget Configuration - Define influencer tier preferences based on budget

📝 Message Templates

• Template Library - Pre-built templates for different collaboration types
• Custom Variables - Use placeholders for personalized messaging
• Tone Variations - Templates for formal, casual, and creative communications
• A/B Testing Support - Create multiple versions for testing

---

🛠 Technology Stack

Backend

Technology	Purpose
Node.js	Server runtime environment
Express.js	Web application framework
MongoDB	NoSQL database for data persistence
Nodemailer	Email sending with SMTP support
JWT	Secure authentication tokens
Google Gemini SDK	AI/ML capabilities

Frontend

Technology	Purpose
HTML5/CSS3	Structure and styling
Vanilla JavaScript	Interactive functionality
Custom UI Components	Unified dashboard and modals
Responsive Design	Mobile-friendly interface

DevOps & Tools

Technology	Purpose
Docker	Containerization
Nginx	Reverse proxy and load balancing
PM2	Process management
Jest	Testing framework

---

📁 Project Structure

RabittAIProject/
├── src/                          # Backend source code
│   ├── config/                   # Configuration files
│   │   ├── database.js           # MongoDB connection setup
│   │   ├── dbInit.js             # Database initialization
│   │   └── systemTemplates.js    # Default message templates
│   ├── middleware/               # Express middleware
│   │   ├── aiMiddleware.js       # AI request handling
│   │   ├── auth.js               # Authentication middleware
│   │   ├── errorHandler.js       # Error handling middleware
│   │   └── validation.js         # Input validation & rate limiting
│   ├── models/                   # Database models & schemas
│   ├── routes/                   # API route handlers
│   │   ├── aiRoutes.js           # AI feature endpoints
│   │   ├── analytics.js          # Analytics endpoints
│   │   ├── auth.js               # Authentication endpoints
│   │   ├── brand.js              # Brand profile endpoints
│   │   ├── campaigns.js          # Campaign management endpoints
│   │   ├── influencers.js        # Influencer data endpoints
│   │   └── messageTemplates.js   # Template management endpoints
│   ├── services/                 # Business logic services
│   │   ├── AuthService.js        # Authentication logic
│   │   ├── BrandAlignmentService.js    # Alignment scoring
│   │   ├── DatabaseService.js    # Database operations
│   │   ├── EmailService.js       # Email sending logic
│   │   ├── EmailIntegrationService.js  # Advanced email features
│   │   ├── geminiService.js      # Google Gemini AI integration
│   │   ├── InfluencerDataService.js    # Influencer data management
│   │   ├── OptimizedDatabaseService.js # Performance-optimized queries
│   │   ├── PerformanceMonitoringService.js # System monitoring
│   │   └── repositories.js       # Data access layer
│   ├── utils/                    # Utility functions
│   │   ├── ErrorHandler.js       # Enhanced error handling
│   │   ├── environmentValidator.js     # Environment validation
│   │   └── errors.js             # Custom error classes
│   └── server.js                 # Main server entry point
├── public/                       # Frontend static files
│   ├── css/                      # Stylesheets
│   │   ├── styles.css            # Main styles
│   │   ├── aiStyles.css          # AI feature styles
│   │   ├── enhanced-ui.css       # Enhanced UI components
│   │   ├── unifiedDashboard.css  # Dashboard styles
│   │   └── ...                   # Other stylesheets
│   ├── js/                       # JavaScript files
│   │   ├── app.js                # Main application
│   │   ├── aiFeatures.js         # AI feature handlers
│   │   ├── aiUI.js               # AI UI components
│   │   ├── analytics.js          # Analytics dashboard
│   │   ├── brand.js              # Brand management
│   │   ├── campaignManager.js    # Campaign management
│   │   ├── influencerDiscovery.js      # Discovery interface
│   │   ├── unifiedDashboard.js   # Unified AI dashboard
│   │   └── ...                   # Other scripts
│   ├── index.html                # Main dashboard
│   ├── analytics.html            # Analytics page
│   ├── campaigns.html            # Campaigns page
│   └── templates.html            # Templates page
├── scripts/                      # Utility scripts
│   ├── build-css.js              # CSS build script
│   ├── build-js.js               # JS build script
│   ├── deploy.js                 # Deployment script
│   ├── health-check.js           # Health check utility
│   └── ...                       # Other scripts
├── tests/                        # Test files
│   ├── api/                      # API tests
│   ├── integration/              # Integration tests
│   └── *.test.js                 # Unit tests
├── docs/                         # Documentation
│   ├── api-documentation.md      # API reference
│   ├── brand-profile-setup.md    # Brand setup guide
│   ├── database-setup.md         # Database configuration
│   ├── email-outreach-setup.md   # Email setup guide
│   └── user-guide.md             # User manual
├── .env.example                  # Environment variables template
├── Dockerfile                    # Docker configuration
├── docker-compose.yml            # Docker Compose setup
├── nginx.conf                    # Nginx configuration
├── ecosystem.config.js           # PM2 configuration
└── package.json                  # Project dependencies

---

🚀 Quick Start

Prerequisites

• Node.js 18.x or higher
• MongoDB 6.x or higher (local or Atlas)
• npm or yarn
• Google Gemini API Key (for AI features)

Installation

1. Clone the repository

   git clone https://github.com/your-username/RabittAIProject.git
   cd RabittAIProject

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env

   Edit .env with your configuration:

   # Database
   MONGODB_URI=mongodb://localhost:27017/icy_database
   
   # Server
   PORT=3000
   NODE_ENV=development
   
   # Email (Mailtrap for testing)
   SMTP_HOST=sandbox.smtp.mailtrap.io
   SMTP_PORT=2525
   SMTP_USER=your_mailtrap_username
   SMTP_PASS=your_mailtrap_password
   
   # AI (Google Gemini)
   GEMINI_API_KEY=your_gemini_api_key
   
   # Security
   JWT_SECRET=your_jwt_secret
   SESSION_SECRET=your_session_secret

4. Start MongoDB (if running locally)

   mongod

5. Start the development server

   npm run dev

6. Open the application Navigate to http://localhost:3000 in your browser.

---

⚙️ Configuration

Environment Variables

Variable	Required	Description	Default
MONGODB_URI	✅	MongoDB connection string	-
PORT	❌	Server port	3000
NODE_ENV	❌	Environment mode	development
GEMINI_API_KEY	❌*	Google Gemini API key	-
SMTP_HOST	❌*	SMTP server host	-
SMTP_PORT	❌*	SMTP server port	-
SMTP_USER	❌*	SMTP username	-
SMTP_PASS	❌*	SMTP password	-
JWT_SECRET	✅	JWT signing secret	-
SESSION_SECRET	✅	Session secret	-
AI_RATE_LIMIT_REQUESTS	❌	AI requests per window	10
AI_RATE_LIMIT_WINDOW_MS	❌	AI rate limit window	60000

*Required for full functionality

Feature Availability

The application validates environment configuration on startup and will indicate which features are available:

✅ AI Features: Available
✅ Email Services: Available

---

📡 API Reference

Base URL

http://localhost:3000/api

Authentication Endpoints

Method	Endpoint	Description
POST	/auth/login	User login
POST	/auth/register	User registration
GET	/auth/verify	Verify JWT token

Influencer Endpoints

Method	Endpoint	Description
GET	/influencers	Get all influencers with pagination
GET	/influencers/search	Search influencers with filters
GET	/influencers/:id	Get specific influencer
POST	/influencers/alignment	Calculate brand alignment scores

Brand Endpoints

Method	Endpoint	Description
GET	/brand/profile	Get brand profile
POST	/brand/profile	Create/update brand profile
GET	/brand/recommendations	Get AI recommendations

Campaign Endpoints

Method	Endpoint	Description
GET	/campaigns	Get all campaigns
POST	/campaigns	Create new campaign
GET	/campaigns/:id	Get campaign details
PUT	/campaigns/:id	Update campaign
DELETE	/campaigns/:id	Delete campaign
POST	/campaigns/:id/send	Send campaign emails
GET	/campaigns/:id/status	Get email delivery status

AI Endpoints

Method	Endpoint	Description
POST	/ai/analyze-profile	Analyze influencer profile
POST	/ai/generate-outreach	Generate outreach messages
POST	/ai/content-ideas	Generate content ideas
POST	/ai/check-authenticity	Check influencer authenticity
POST	/ai/match-influencers	Smart influencer matching
POST	/ai/campaign-strategy	Generate campaign strategy
POST	/ai/analyze-image	Analyze image content
POST	/ai/enhanced-alignment	AI-enhanced alignment scores
POST	/ai/bulk-analysis	Bulk influencer analysis
GET	/ai/status	Check AI service status

Template Endpoints

Method	Endpoint	Description
GET	/templates	Get all templates
POST	/templates	Create template
PUT	/templates/:id	Update template
DELETE	/templates/:id	Delete template

Analytics Endpoints

Method	Endpoint	Description
GET	/analytics/dashboard	Get dashboard metrics
GET	/analytics/campaign/:id	Get campaign analytics
GET	/analytics/performance	Get performance metrics

Health Endpoints

Method	Endpoint	Description
GET	/health	Basic health check
GET	/health/detailed	Detailed system health

For detailed API documentation, see docs/api-documentation.md.

---

🎨 Frontend Features

Unified AI Dashboard

A comprehensive interface that combines all AI-powered features in one place:

• Influencer discovery with real-time filtering
• AI-powered analysis with one-click insights
• Brand alignment scoring visualization
• Campaign creation workflow

Key UI Components

• Brand Profile Setup - Step-by-step brand configuration wizard
• Influencer Discovery - Advanced search with filter sidebar
• Campaign Manager - Create, manage, and track campaigns
• Message Templates - Template editor with variable support
• Analytics Dashboard - Visual charts and metrics

Navigation

• 📊 Dashboard - Main overview and quick actions
• 📋 Campaigns - Campaign management
• 📈 Analytics - Performance tracking
• 📝 Templates - Message template management

---

🤖 AI Capabilities

Profile Analysis

The AI analyzes influencer profiles to provide:

• Engagement Quality Score - Assessment of genuine engagement vs. artificial
• Audience Demographics Prediction - Estimated audience breakdown
• Content Style Analysis - Tone, frequency, and quality assessment
• Brand Safety Rating - Risk assessment for brand partnerships

Smart Outreach Generation

Generate personalized messages with:

• Tone Variations - Formal, casual, or creative options
• Brand Voice Adaptation - Messages that match your brand personality
• Context Awareness - References to influencer's recent content
• Campaign-Specific Messaging - Tailored for product launches, events, etc.

Content Ideas

AI-generated collaboration ideas including:

• Content formats (posts, reels, stories)
• Themes and concepts
• Hashtag suggestions
• Posting schedule recommendations

Authenticity Detection

The AI checks for:

• Suspicious follower growth patterns
• Engagement rate anomalies
• Comment quality analysis
• Fake follower indicators

---

📧 Email Integration

Supported Email Providers

• Mailtrap (recommended for testing)
• SendGrid
• Mailgun
• Custom SMTP

Email Features

• HTML email templates with branding
• Personalization variables
• Delivery tracking webhooks
• Bounce handling
• Rate limiting (50 emails/minute)

Configuration

See docs/email-outreach-setup.md for detailed email setup instructions.

---

🧪 Testing

Run All Tests

npm test

Test Categories

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# API tests
npm run test:api

# Full validation (all tests + linting)
npm run validate

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Test Coverage

Tests cover:

• Brand Alignment Service
• Email Service
• Influencer Data Service
• Authentication
• Database operations
• Error handling
• Performance metrics

---

🚢 Deployment

Using Docker

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

Using PM2

# Start with PM2
npm run start:prod

# Or directly with PM2
pm2 start ecosystem.config.js

Environment Setup

1. Set NODE_ENV=production
2. Use a production MongoDB instance (Atlas recommended)
3. Configure production SMTP credentials
4. Set strong JWT and session secrets
5. Enable HTTPS with SSL certificates

Nginx Configuration

The included nginx.conf provides:

• Reverse proxy setup
• SSL/TLS configuration
• Gzip compression
• Caching headers
• Rate limiting

---

🔧 Troubleshooting

Common Issues

MongoDB Connection Failed

❌ Database connection failed

• Ensure MongoDB is running
• Check MONGODB_URI is correct
• Verify network connectivity

AI Features Not Working

❌ AI Features: Disabled

• Check GEMINI_API_KEY is set correctly
• Verify API key is valid and has quota

Email Sending Failed

Email delivery failed

• Verify SMTP credentials
• Check rate limits
• Ensure email addresses are valid

Health Check

# Check system health
npm run health-check

Logs

# View application logs
npm run logs

---

📚 Documentation

Document	Description
API Documentation	Complete API reference
Brand Profile Setup	Guide to configuring brand profiles
Database Setup	MongoDB configuration guide
Email Outreach Setup	Email integration guide
User Guide	End-user manual

---

📜 Available Scripts

Script	Description
npm start	Start production server
npm run start:prod	Start in production mode
npm run dev	Start development server with hot reload
npm run build	Build CSS and JS assets
npm run build:prod	Production build with optimization
npm run test	Run test suite
npm run test:all	Run all tests including integration
npm run validate	Full validation check
npm run health-check	Run health check script
npm run deploy	Deploy with pre-flight checks
npm run deploy:quick	Quick deploy skipping tests
npm run performance:report	Generate performance report

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow the existing code style
• Write tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

---

📄 License

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

---

🙏 Acknowledgments

• Google Gemini for AI capabilities
• MongoDB for database solutions
• Express.js for the web framework
• All contributors who have helped improve this project

---

Built with ❤️ by the ICY Team

⬆ Back to Top