Skip to content

README.md

Latest commit

 

History

History
358 lines (296 loc) · 9.69 KB

README.md

File metadata and controls

358 lines (296 loc) · 9.69 KB

UniMatch Kenya - Complete Setup & Deployment Guide

A free, campus-exclusive dating platform for Kenyan university and college students built with modern, production-ready technologies.

📋 Table of Contents

🎯 Project Overview

UniMatch Kenya is a mobile-first dating application designed specifically for university and college students in Kenya. The platform emphasizes safety, authenticity, and a vibrant campus community experience.

Key Features:

  • Email verification using institutional email domains (.ac.ke, .edu)
  • Swipe-based discovery with intelligent matching
  • Real-time messaging with WebSocket support
  • User safety with reporting and blocking features
  • Profile completeness tracking
  • Responsive design with dark mode support

🛠️ Technology Stack

Backend

  • Framework: Django 5.0 + Django REST Framework
  • Database: PostgreSQL 16
  • Cache & Broker: Redis 7
  • Real-time: Django Channels + Daphne
  • Tasks: Celery with Beat scheduler
  • Server: Gunicorn with Uvicorn workers
  • Proxy: Nginx with rate limiting

Frontend

  • Framework: Next.js 14 with App Router
  • Language: TypeScript
  • State Management: Zustand
  • HTTP Client: Axios
  • Animations: Framer Motion
  • Styling: Tailwind CSS (to be added)
  • Testing: Jest + React Testing Library

Infrastructure

  • Containerization: Docker & Docker Compose
  • Email: SMTP (Gmail recommended for dev)
  • File Storage: Cloudinary
  • Production: Manual scaling with monitoring

🚀 Quick Start

Prerequisites

  • Docker & Docker Compose
  • Node.js 18+ (for frontend development)
  • Python 3.11+ (for backend development)
  • PostgreSQL 16 (if running without Docker)

Local Development with Docker Compose

  1. Clone and setup environment:
cd /home/samdev652/Desktop/UniMatch\ Kenya
cp .env.example .env
# Edit .env with your configuration
  1. Start all services:
docker-compose up --build
  1. Run migrations:
docker-compose exec backend python manage.py migrate
docker-compose exec backend python manage.py createsuperuser
  1. Access the application:

Manual Development Setup

Backend:

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export DJANGO_SETTINGS_MODULE=unmatch_kenya.settings.development
python manage.py migrate
python manage.py runserver

Frontend:

cd frontend
npm install
npm run dev

Redis (macOS with Homebrew):

brew install redis
redis-server

🏗️ Architecture

Directory Structure

UniMatch Kenya/
├── backend/
│   ├── unmatch_kenya/           # Main Django project
│   │   ├── settings/            # Base, dev, production configs
│   │   ├── asgi.py              # Channels config
│   │   ├── wsgi.py              # WSGI config
│   │   ├── celery.py            # Celery config
│   │   └── urls.py              # URL routing
│   ├── apps/
│   │   ├── users/               # Authentication & user management
│   │   ├── profiles/            # User profile & photos
│   │   ├── matching/            # Swipe algorithm & matches
│   │   ├── messaging/           # Chat & WebSocket
│   │   ├── notifications/       # In-app notifications
│   │   └── reports/             # Moderation system
│   ├── core/                    # Shared utilities
│   ├── manage.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── app/                     # Next.js App Router pages
│   ├── components/              # React components
│   ├── hooks/                   # Custom React hooks
│   ├── store/                   # Zustand stores
│   ├── lib/                     # Utilities (API client, etc)
│   ├── types/                   # TypeScript definitions
│   ├── __tests__/               # Jest tests
│   ├── package.json
│   ├── tsconfig.json
│   ├── next.config.js
│   └── Dockerfile
├── infrastructure/
│   └── nginx/                   # Nginx configuration
├── docker-compose.yml
├── .env.example
├── .gitignore
├── .editorconfig
└── README.md

Data Models Relationship

User (1) ───────► UserProfile (1)
  │                    │
  ├──► VerificationOTP │──► ProfilePhoto
  │                    │
  ├──► UserBlock       └──► ProfileInterest
  │
  ├──► Swipe ◄────►User (Many-to-Many via swipe)
  │
  ├──► Match
  │      │
  │      └──► Message
  │              │
  │              └──► User (sender)
  │
  ├──► Notification
  │
  └──► Report

📊 Database Schema Highlights

Connection Pooling

  • Pool size: 20 connections
  • Max overflow: 10 additional connections
  • Timeout: 600 seconds (auto-reconnect)

Indexes

-- Swipes: Quick access by swiper & swiped
CREATE INDEX idx_swipes_swiper ON swipes(swiper_id, created_at DESC);
CREATE INDEX idx_swipes_swiped ON swipes(swiped_id, created_at DESC);

-- Messages: Efficient chat retrieval
CREATE INDEX idx_messages_match ON messages(match_id, created_at DESC);

-- Users: Location & activity queries
CREATE INDEX idx_users_campus ON users(campus, last_active DESC);

🔌 API Endpoints

Base URL: /api/v1/

Authentication

POST   /auth/register/          - Register new user
POST   /auth/verify/            - Verify email with OTP
POST   /auth/login/             - Login (JWT)
POST   /auth/refresh/           - Refresh token
GET    /auth/me/                - Current user profile
PATCH  /auth/me/update/         - Update profile

Profiles

GET    /profiles/my_profile/    - Get user's profile
POST   /profiles/upload_photo/  - Upload profile photo
POST   /profiles/add_interests/ - Add interests
PATCH  /profiles/update_bio/    - Update bio & looking_for

Discovery & Matching

GET    /matching/discover/feed/ - Get discover feed (20 candidates)
POST   /matching/discover/like/ - Like a profile
POST   /matching/discover/pass_profile/ - Pass on profile
GET    /matching/matches/       - List all active matches
POST   /matching/matches/{id}/unmatch/ - Unmatch with user

Messaging

GET    /messages/conversations/ - Get all conversations
POST   /messages/send_message/  - Send message in match
POST   /messages/mark_as_read/  - Mark messages as read

WebSocket: /ws/chat/{match_id}/

Notifications

GET    /notifications/          - List notifications
GET    /notifications/unread/   - Get unread count
POST   /notifications/{id}/mark_as_read/ - Mark as read
POST   /notifications/mark_all_as_read/

Reports

POST   /reports/report_user/    - Submit report
GET    /reports/                - List user's reports

🚀 Deployment

Environment Variables

Critical variables for production:

DEBUG=False
SECRET_KEY=<generate-strong-key>
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
DATABASE_URL=postgresql://user:pass@host:5432/dbname
REDIS_URL=redis://host:6379/0
CLOUDINARY_CLOUD_NAME=<your-cloud-name>
CLOUDINARY_API_KEY=<api-key>
CLOUDINARY_API_SECRET=<api-secret>
EMAIL_HOST_USER=<gmail@example.com>
EMAIL_HOST_PASSWORD=<app-password>
CORS_ALLOWED_ORIGINS=https://yourdomain.com
JWT_EXPIRATION_HOURS=1
JWT_REFRESH_EXPIRATION_DAYS=7

Production Checklist

  • Set DEBUG=False
  • Generate secure SECRET_KEY
  • Configure PostgreSQL connection pooling
  • Set up Redis persistence
  • Configure Cloudinary for image moderation
  • Set up HTTPS/SSL certificates
  • Configure email backend (SendGrid/Mailgun recommended)
  • Set up log aggregation (Sentry)
  • Configure database backups
  • Set up monitoring & alerting

Using Gunicorn

gunicorn --workers=4 \
         --worker-class=uvicorn.workers.UvicornWorker \
         --bind=0.0.0.0:8000 \
         --timeout=30 \
         unmatch_kenya.wsgi:application

✅ Testing & Monitoring

Backend Testing

# Run all tests
pytest

# With coverage
pytest --cov=apps --cov-report=html

# Specific app
pytest apps/users/tests/

# Watch mode
pytest-watch

Frontend Testing

# Run unit tests
npm test

# With coverage
npm run test:coverage

# Watch mode
npm test -- --watch

Load Testing

# Using Locust - simulate 600 concurrent users
locust -f tests/load_test.py --host=http://localhost:8000

Monitoring

  • Database: Monitor slow queries, connection pool utilization
  • Redis: Monitor memory usage, eviction policies
  • Celery: Monitor task queue length, worker availability
  • WebSocket: Monitor active connections, message throughput
  • Response times: API latency, WebSocket message delivery

📝 Contributing

  1. Create a feature branch: git checkout -b feature/your-feature
  2. Make changes following the project conventions
  3. Write tests for new features
  4. Run linting: black . && flake8 apps/
  5. Commit with clear messages
  6. Push and create a Pull Request

📄 License

Proprietary - UniMatch Kenya 2026

Questions or Issues? Create an issue or contact the development team.