Refferq - Open Source Affiliate Management Platform

A powerful, feature-rich affiliate marketing platform built with Next.js 15 and PostgreSQL

Features • Tech Stack • Installation • Deployment • Documentation • License

---

📋 About

Refferq is a comprehensive affiliate management platform designed to help businesses create, manage, and scale their affiliate programs. Built with modern web technologies, it provides a complete solution for tracking referrals, managing commissions, and engaging with affiliate partners.

🎯 Key Highlights

• Complete Affiliate Portal - Full-featured dashboard for affiliates to track earnings, submit leads, and manage payouts
• Admin Control Panel - Comprehensive admin dashboard for managing partners, referrals, and program settings
• Real-time Analytics - Track conversions, commissions, and performance metrics in real-time
• Automated Workflows - Automated commission calculations, payout processing, and email notifications
• Flexible Commission Rules - Support for percentage-based and fixed commission structures
• White-Label Ready - Customizable branding and subdomain support

---

✨ Features

For Admins

• Dashboard Analytics

  • Real-time revenue tracking
  • Conversion rate analytics
  • Partner performance metrics
  • Visual charts and reports

• Partner Management

  • Approve/reject affiliate applications
  • Manage partner groups
  • Set custom commission rates
  • View partner activity logs

• Referral Management

  • Review and approve lead submissions
  • Track referral status (Pending, Approved, Rejected)
  • Manual lead conversion tracking
  • Bulk operations support

• Commission & Payouts

  • Automated commission calculations
  • Flexible commission rules
  • Payout scheduling (NET-15, NET-30, etc.)
  • Multiple payout methods (PayPal, Bank Transfer, Stripe, Wise)

• Program Settings

  • Customizable program details
  • Branding configuration (colors, logos)
  • Cookie tracking settings
  • Country blocking
  • Terms of Service management

• Email Automation

  • Welcome emails for new partners
  • Referral notification emails
  • Commission approval alerts
  • Payout confirmation emails
  • Customizable email templates

For Affiliates

• Personal Dashboard

  • Earnings overview (total, pending, paid)
  • Click tracking
  • Lead conversion metrics
  • Recent referral activity

• Referral Management

  • Submit leads manually
  • Track referral status
  • View commission breakdown
  • Filter by status (All, Pending, Approved)

• Marketing Resources

  • Unique referral link
  • Shareable referral code
  • Copy-to-clipboard functionality
  • Social media sharing buttons

• Payout Tracking

  • View payout history
  • Track payout status
  • Next payout schedule
  • Earnings breakdown

• Account Settings

  • Update personal details
  • Configure payment methods
  • Set payout preferences
  • Manage notification settings

---

🛠️ Tech Stack

Core Framework

• Next.js 15.2.3 - React framework with App Router
• React 19 - UI library
• TypeScript - Type safety

Database & ORM

• PostgreSQL - Primary database
• Prisma - Modern ORM with type safety

Authentication & Security

• JWT (jose) - JSON Web Tokens for auth
• bcryptjs - Password hashing
• OTP Verification - Email-based verification

Styling

• Tailwind CSS - Utility-first CSS
• Recharts - Data visualization charts

Email

• Resend - Modern email API for transactional emails
• Email Templates - Customizable HTML templates

Development

• ESLint - Code linting
• Prettier - Code formatting
• TypeScript - Static typing

---

🚀 Installation

Prerequisites

• Node.js 18.x or higher
• PostgreSQL 14.x or higher
• npm or yarn or pnpm

Step 1: Clone the Repository

git clone https://github.com/yourusername/refferq.git
cd refferq

Step 2: Install Dependencies

npm install
# or
yarn install
# or
pnpm install

Step 3: Environment Setup

Create a .env.local file in the root directory:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/refferq"

# JWT Secret (generate a secure random string)
JWT_SECRET="your-super-secret-jwt-key-min-32-chars"

# Email Configuration (Resend)
# Sign up at https://resend.com for free API key
RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
RESEND_FROM_EMAIL="Refferq <[email protected]>"

# Admin Notification Emails (comma-separated)
ADMIN_EMAILS="[email protected]"

# Application URL
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Optional: Stripe (for payments)
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_PUBLISHABLE_KEY="pk_test_..."

Step 4: Database Setup

# Generate Prisma Client
npx prisma generate

# Push schema to database
npx prisma db push

# (Optional) Seed database with sample data
npx prisma db seed

Step 5: Email Configuration

Refferq uses Resend for sending transactional emails. Follow these steps:

1. Sign up for Resend

   • Go to https://resend.com
   • Create a free account (3,000 emails/month)

2. Get your API Key

   • Navigate to API Keys in Resend dashboard
   • Create a new API key
   • Copy the key (starts with re_...)

3. Update .env.local

   RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   RESEND_FROM_EMAIL="Refferq <[email protected]>"
   ADMIN_EMAILS="[email protected]"

4. Test Email Setup (Optional)

   curl -X POST http://localhost:3000/api/admin/emails/test \
     -H "Content-Type: application/json" \
     -d '{"type": "welcome", "to": "[email protected]"}'

Note: For production, verify your domain in Resend dashboard to use your own email addresses. See docs/EMAIL.md for detailed configuration guide.

Step 6: Run Development Server

npm run dev

Open https://app.refferq.com or your configured domain in your browser.

or

yarn dev

or

pnpm dev

Open [http://localhost:3000](http://localhost:3000) in your browser.

### Step 7: Create Admin Account

1. Register at `/register`
2. Use the registration form to create your account
3. Manually update the user role in the database:

```sql
UPDATE users SET role = 'ADMIN', status = 'ACTIVE' WHERE email = '[email protected]';

Note: New affiliates are set to PENDING status by default and require admin approval. Admins should be set to ACTIVE status.

---

📦 Deployment

Deploy on Vercel

The easiest way to deploy Refferq is using Vercel:

Manual Deployment Steps:

1. Push to GitHub

   git push origin main

2. Import Project in Vercel

   • Go to Vercel Dashboard
   • Click "New Project"
   • Import your repository

3. Configure Environment Variables

   • Add all variables from .env.local
   • Set DATABASE_URL to your production database

4. Deploy

   • Vercel will automatically build and deploy
   • Get your production URL: https://your-project.vercel.app

For detailed deployment instructions, see DEPLOYMENT.md

---

📚 Documentation

• API Documentation - Complete API reference
• Deployment Guide - Production deployment steps
• Database Schema - Database structure and models
• Email Configuration - Email setup and templates guide
• Contributing Guide - How to contribute

---

🗂️ Project Structure

refferq/
├── prisma/
│   └── schema.prisma          # Database schema
├── public/
│   └── images/                # Static assets
├── src/
│   ├── app/
│   │   ├── admin/            # Admin dashboard
│   │   ├── affiliate/        # Affiliate dashboard
│   │   ├── api/              # API routes
│   │   │   ├── admin/        # Admin endpoints
│   │   │   ├── affiliate/    # Affiliate endpoints
│   │   │   └── auth/         # Authentication
│   │   ├── login/            # Login page
│   │   └── register/         # Registration page
│   ├── components/           # React components
│   ├── hooks/                # Custom hooks
│   ├── context/              # React context
│   └── icons/                # SVG icons
├── docs/                     # Documentation
├── .env.local                # Environment variables
├── vercel.json              # Vercel configuration
└── README.md                # This file

---

🔧 Configuration

Program Settings

Configure your affiliate program through the Admin Dashboard:

1. General Settings

   • Product name and program name
   • Website URL
   • Currency (INR, USD, EUR, GBP)
   • Blocked countries

2. Branding

   • Brand colors (background, button, text)
   • Company logo
   • Favicon

3. Payout Settings

   • Minimum payout threshold
   • Payout term (NET-15, NET-30, NET-45)
   • Supported payout methods

4. Marketing & Tracking

   • Cookie duration
   • URL parameters
   • Manual lead submission
   • Social media ad blocking

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

---

📄 License

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

---

👨‍💻 Author

Developed by: Refferq Team

• GitHub: @refferq
• Website: https://refferq.com

---

🌟 Show Your Support

If you find this project useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 🔀 Submitting pull requests

---

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

🙏 Acknowledgments

Built with ❤️ using:

• Next.js
• Prisma
• Tailwind CSS
• Recharts

---

Made with ❤️ by the Refferq Team

_{© 2025 Refferq. All rights reserved.}

**⭐ Found this useful? Give us a star to support the project!**