ShiftPay is a Django-based platform that provides instant salary advances to Nigerian gig workers using AI-powered trust scoring. Workers can log their shifts, build a trust score, and receive advances based on their earnings history — no collateral required.
- User Authentication: Secure registration with job type, phone number, and daily earnings
- Shift Logging: Track daily work hours, earnings, and job descriptions
- AI Trust Score: Machine learning-powered scoring based on shift patterns and earnings consistency
- Instant Advance Requests: Request salary advances with AI-powered approval decisions
- Multiple Payout Methods: OPay, PalmPay, Bank Transfer, or Cash Agent pickup
- Repayment Scheduling: Automatic 14-day repayment with 10% flat fee
- AI Earnings Insights: Daily personalized insights powered by Google Gemini AI
- Dashboard: Real-time overview of shifts, earnings, trust score, and eligibility
- Mobile-First Design: Optimized for gig workers who use smartphones
Before you begin, ensure you have the following installed:
- Python 3.8 or higher - Download Python
- pip (Python package manager) - Usually comes with Python
- Git - Download Git
- Virtual Environment (recommended) -
python -m venv
git clone <repository-url>
cd PayTrackWindows:
python -m venv venv
venv\Scripts\activateMac/Linux:
python3 -m venv venv
source venv/bin/activatepip install django google-generativeai python-decoupleCreate a .env file in the project root:
DEBUG=True
SECRET_KEY=your-secret-key-here
GEMINI_API_KEY=your-gemini-api-key-hereImportant: Get your Gemini API key from Google AI Studio
python manage.py makemigrations
python manage.py migrateTo access the Django admin panel:
python manage.py createsuperuserFollow the prompts to create an admin account.
python manage.py runserverThe application will be available at: http://127.0.0.1:8000
- Landing Page: http://127.0.0.1:8000/
- Login: http://127.0.0.1:8000/login/
- Register: http://127.0.0.1:8000/register/
- Dashboard: http://127.0.0.1:8000/dashboard/
- Log Shift: http://127.0.0.1:8000/shift/log/
- Request Advance: http://127.0.0.1:8000/advance/request/
- Admin Panel: http://127.0.0.1:8000/admin/
PayTrack/
├── App/ # Main application directory
│ ├── __init__.py
│ ├── admin.py # Django admin configuration
│ ├── apps.py # App configuration
│ ├── models.py # Database models (WorkerProfile, ShiftLog, AdvanceRequest, RepaymentSchedule)
│ ├── urls.py # App URL patterns
│ └── views.py # View functions (dashboard, log_shift, advance_request, AI insights)
├── PayTrack/ # Project configuration directory
│ ├── __init__.py
│ ├── settings.py # Django settings
│ ├── urls.py # Project URL patterns
│ └── wsgi.py # WSGI configuration
├── static/ # Static files (CSS, JS, images)
│ └── css/
│ ├── index.css # Landing page styles
│ ├── auth.css # Authentication page styles
│ └── dashboard.css # Dashboard styles
├── templates/ # HTML templates
│ ├── index.html # ShiftPay landing page
│ ├── login.html # Login page
│ ├── register.html # Registration page with ShiftPay fields
│ ├── dashboard.html # Worker dashboard with AI insights
│ ├── advance_request.html # Advance request form with payout methods
│ └── advance_result.html # AI decision result page
├── media/ # User-uploaded files
├── db.sqlite3 # SQLite database (default)
├── manage.py # Django management script
└── .env # Environment variables (GEMINI_API_KEY)
The application includes a custom authentication system with the following features:
- Email-based registration with full name
- Job type selection (Uber/Bolt Driver, Bus Driver, Market Trader, Artisan, Delivery Rider, Other)
- Phone number collection
- Daily average earnings input
- Password validation (minimum 8 characters)
- Automatic WorkerProfile creation
- Email and password authentication
- Session management
- Redirects logged-in users to dashboard
- Advance Decision AI: Uses Google Gemini (gemini-1.5-flash) to make instant, fair advance approval decisions
- Earnings Insight AI: Generates daily personalized insights based on shift patterns and earnings data
- Warm, Human-like Responses: AI is configured to speak like it understands Nigerian gig worker hustle
- Base score of 50 points
- Bonus points for total shifts logged (+10 for 3+ shifts, +15 for 5+ shifts)
- Earnings stability bonus (within 30% of daily average)
- Volume bonus (if earnings today > daily average)
- Hackathon mode: No penalty for gaps between shifts (allows same-day logging)
- Minimum 3 shifts logged (down from 5 for hackathon)
- Trust score of 50+ (down from 60 for hackathon)
- Max advance amount: 50% of last 7 days earnings
Status: Live Now
- Workers manually log their shifts with hours, earnings, and job descriptions
- AI calculates trust score based on shift patterns and earnings consistency
- Instant advance decisions powered by Gemini AI
- Multiple payout methods (OPay, PalmPay, Bank Transfer, Cash Agent)
- Repayment scheduling with automatic daily deductions
Status: Planned
- Direct API integration with ride-hailing platforms
- Automatic earnings verification and import
- Reduced fraud risk with verified data
- Faster trust score building
- Real-time earnings tracking
Status: Planned
- Partnership with licensed Nigerian microfinance institutions
- Real capital deployment for advances
- Regulatory compliance and licensing
- Larger advance amounts with institutional backing
- Credit bureau integration for broader financial inclusion
Status: Planned
- USSD-based interface for feature phone users
- Voice and SMS support for accessibility
- Expanded reach to underserved workers
- Offline capability for areas with poor connectivity
- Agent network for cash-in/cash-out services
Generate a new secret key:
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"Update SECRET_KEY in PayTrack/settings.py or .env file.
By default, ShiftPay uses SQLite. To use PostgreSQL or MySQL:
PostgreSQL:
pip install psycopg2-binaryUpdate DATABASES in PayTrack/settings.py:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'shiftpay_db',
'USER': 'your_username',
'PASSWORD': 'your_password',
'HOST': 'localhost',
'PORT': '5432',
}
}pip install google-generativeai- Verify your
GEMINI_API_KEYin.envfile - Check that the API key is valid and has credits
- The app has fallback logic to auto-approve if API fails
- Ensure you're logging shifts with valid hours and earnings
- Check that the WorkerProfile is created for the user
- Try logging 3+ shifts to see the trust score increase
- Ensure you have logged at least 3 shifts
- Check that your trust score is 50+
- Verify your last 7 days earnings are sufficient
python manage.py testpython manage.py makemigrations
python manage.py migratepython manage.py shell- Set
DEBUG = FalseinPayTrack/settings.py - Update
ALLOWED_HOSTSwith your domain - Use a production database (PostgreSQL recommended)
- Configure static files serving
- Set up a production web server (Gunicorn + Nginx)
- Secure your environment variables
Use environment variables for sensitive information:
import os
GEMINI_API_KEY = os.getenv('GEMINI_API_KEY')
SECRET_KEY = os.getenv('SECRET_KEY')This project is licensed under the MIT License.
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
If you encounter any issues or have questions, please open an issue on the repository.
- Django Framework
- Google Gemini AI
- Bootstrap 5
- All contributors and users of ShiftPay
Built with ❤️ using Django & Google Gemini AI