USSD Job Board

Overview

The USSD Job Board is a platform designed to connect job seekers and employers in Kenya through a simple, accessible USSD interface. By leveraging USSD technology, the platform enables users without smartphones or internet access to search and apply for jobs, and for employers to post job opportunities, all via basic mobile phones.

Key Features

• USSD Job Search: Job seekers can search and apply for jobs using a USSD menu on any mobile phone.
• Employer Portal: Employers can post job listings and manage applications.
• Location-Based Matching: Jobs are matched to seekers based on their location (county, sub-county, ward).
• Application Management: Track job applications and statuses.
• Payment Integration: Supports mobile payments (e.g., M-Pesa) for premium job postings.
• User Types: Supports both job seekers and employers with tailored experiences.

How It Works

1. Job Seekers:
   • Dial a USSD code (e.g., *123#) to access the job board menu.
   • Browse or search for jobs by category or location.
   • Apply for jobs directly from the USSD menu.
2. Employers:
   • Register and post job opportunities via the web API or USSD.
   • Manage job listings and view applications.
3. Matching:
   • The system matches job seekers to jobs based on their profile and location.

System Architecture

• Backend: FastAPI (Python)
• Database: PostgreSQL (with SQLAlchemy ORM)
• Task Queue: Celery with Redis
• USSD Integration: Africa's Talking API
• Payments: M-Pesa integration
• Containerization: Docker & Docker Compose

Directory Structure

• app/ - Main application code
  • api/ - API endpoints (USSD, jobs, applications, payments, users, employers)
  • models/ - Database models (Job, User, Application, etc.)
  • services/ - Business logic and integrations
  • schemas/ - Pydantic schemas for data validation
  • core/ - Configuration, database, and security
  • utils/ - Utility functions
• scripts/ - Utility scripts (e.g., loading Kenya locations)

API Overview

• USSD Endpoint: /api/v1/ussd/callback (POST)
  • Handles USSD requests from Africa's Talking.
• Jobs API: /api/v1/jobs/
  • GET /nearby - Find jobs near a location (requires authentication)
  • POST / - Create a new job (employers only)
• Other APIs: Applications, Payments, Users, Employers (see code for details)

Data Models (Simplified)

• User:
  • id, phone_number, full_name, age, education_level, skills, county, user_type, etc.
• Job:
  • id, employer_id, title, description, category, requirements, salary_range, location, status, etc.
• Application:
  • Job applications linking users to jobs.

Setup & Deployment

Prerequisites

• Docker & Docker Compose
• (Optional) Python 3.8+ and pip for local development

Quick Start (Docker)

1. Clone the repository:

   git clone <repo-url>
   cd ussd_job

2. Copy and configure your .env file with the required environment variables (see below).
3. Start the services:

   docker-compose up --build

4. The API will be available at http://localhost:8000.

Local Development

1. Install dependencies:

   pip install -r requirements.txt

2. Set up PostgreSQL and Redis (see docker-compose.yml for configuration).
3. Run database migrations (if any).
4. Start the FastAPI server:

   uvicorn app.main:app --reload

Loading Kenya Locations

To load location data (counties, sub-counties, wards):

python scripts/load_kenya_locations.py

Environment Variables

Set these in your .env file:

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection string
• MPESA_CONSUMER_KEY, MPESA_CONSUMER_SECRET, MPESA_SHORTCODE, MPESA_PASSKEY - M-Pesa API credentials
• AFRICAS_TALKING_API_KEY, AFRICAS_TALKING_USERNAME - Africa's Talking API credentials
• SECRET_KEY - JWT secret
• ALGORITHM - JWT algorithm (default: HS256)
• ACCESS_TOKEN_EXPIRE_MINUTES - Token expiry (default: 30)

Technologies Used

• FastAPI, SQLAlchemy, Alembic
• PostgreSQL, Redis, Celery
• Africa's Talking, M-Pesa
• Docker, Docker Compose

Developers

1. Nelson Njihia — nelsonnjihia2006@gmail.com
2. Elizabeth Julius — bethjulius08@gmail.com

Contributing

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

Contact

For questions or support, please contact the maintainers at

1 nelsonnjihia2006@gmail.com 2 bethjulius08@gmail.com