Launch Docker Services

docker-compose up -d

To stop Docker services:

docker-compose down

To rebuild and restart services:

docker-compose up --build

Run Tests

Run all tests

docker-compose -f docker-compose.test.yml up --build   //bizzard

Run all tests for the authentication app:

docker-compose exec web pytest apps/authentication/tests/ -v //bizzard

Run specific test files:

docker-compose exec web pytest apps/referrals/tests/test_service.py -v

To run tests in the background with Docker:

docker-compose up -d --build

---

Referral System API

A Django-based RESTful API service for managing referral systems with JWT authentication, async operations, and third-party integrations.

Features

• User authentication with JWT and OAuth 2.0
• Referral code management
• Email verification with Email Hunter
• User data enrichment with Clearbit
• Redis caching for improved performance
• Comprehensive API documentation
• Asynchronous operations
• PostgreSQL database

Prerequisites

• Docker and Docker Compose
• Python 3.11+
• PostgreSQL 13+
• Redis 6+

Quick Start

1. Clone the repository:

git clone https://github.com/yourusername/referral-system.git
cd referral-system

2. Create a .env file:

cp .env.example .env

3. Build and start services:

docker-compose up --build

4. Run migrations:

docker-compose exec web python manage.py migrate

5. Access the API:

• API: http://localhost:8000/api/v1/
• Documentation: http://localhost:8000/swagger/

API Documentation

Authentication

Register User

POST /api/v1/auth/register/
Content-Type: application/json

{
    "email": "[email protected]",
    "password": "secure_password",
    "first_name": "John",
    "last_name": "Doe"
}

Login

POST /api/v1/auth/login/
Content-Type: application/json

{
    "email": "[email protected]",
    "password": "secure_password"
}

Referral Management

Create Referral Code

POST /api/v1/referrals/codes/create/
Authorization: Bearer <token>
Content-Type: application/json

{
    "expires_at": "2024-12-31T23:59:59Z"
}

Register with Referral Code

POST /api/v1/referrals/register/
Content-Type: application/json

{
    "referral_code": "CODE123",
    "email": "[email protected]",
    "password": "secure_password"
}

Development

Running Tests

docker-compose exec web pytest  //bizard

Run a specific test file:

docker-compose exec web pytest apps/referrals/tests/test_views.py    

Deployment

Production Setup

1. Update environment variables:

   • DEBUG=0
   • Secure SECRET_KEY
   • Database credentials
   • API keys for Clearbit and Email Hunter

2. Build and deploy:

docker-compose -f docker-compose.prod.yml up --build

Security Considerations

• Use HTTPS in production
• Regularly rotate JWT secrets
• Monitor API rate limits
• Keep dependencies updated
• Regular security audits

Third-Party Integrations

Clearbit

Used for enriching user data during registration. Configured via:

• CLEARBIT_API_KEY in .env

Email Hunter

Verifies email addresses during registration. Configured via:

• EMAILHUNTER_API_KEY in .env

Caching

Redis is used for caching:

• Referral codes
• Enriched user data
• API responses

Configure cache settings in settings.py:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://redis:6379/0',
    }
}

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request