learner

Swipe right on knowledge: Match with classmates to teach, learn, and study together.

Overview

Learnr is a Tinder-style educational platform that connects students based on their courses and skills. Swipe through profiles, match with peers, and meet up to teach each other or study together—making learning collaborative and social.

In today's educational landscape, students often struggle to find the right study partners or tutors within their peer group. Learnr bridges this gap by creating a secure, student-exclusive community where knowledge sharing is just a swipe away.

Key Features

Secure Student Verification

AI-Powered ID Verification: Upload your student ID and let our multimodal AI verify your identity automatically
Uses GPT-4 Vision to extract and verify name and student ID
Instant verification with visual confirmation
Exclusive access for verified students
Safe and trusted learning environment

Skill-Based Matching

List courses you need help with
Showcase subjects you're confident teaching
Get matched with complementary learners
Smart matching algorithm finds optimal study partners

Real-Time Messaging

Instant chat with matched students
Typing indicators and read receipts
Unread message notifications
Persistent conversation history

Personalized Profiles

Custom profile pictures with avatar generation
Bio and course preferences
Verification badges
Edit profile information

Course Management

Browse and select from available courses
Specify courses you can teach
Indicate courses you want to learn
Create new course listings

Tech Stack

Backend

Framework: Flask 3.0.0
Database: PostgreSQL with SQLAlchemy ORM
Authentication: JWT (Flask-JWT-Extended)
Real-time Communication: Flask-SocketIO
AI Integration: OpenAI GPT-4 Vision API
Migrations: Flask-Migrate (Alembic)

Frontend

Framework: React 18.2.0
Build Tool: Vite 5.0.8
Routing: React Router DOM 6.21.0
Styling: Tailwind CSS 3.4.0
HTTP Client: Axios 1.6.5
Real-time: Socket.IO Client

Database Schema

Users: Student profiles with authentication and verification
Courses: Course catalog with codes and descriptions
Matches: User matching system with swipe history
Messages: Real-time chat with read status tracking

Installation

Prerequisites

Python 3.9 or higher
Node.js 18 or higher
PostgreSQL 12 or higher
OpenAI API key (for student verification)

Backend Setup

Clone the repository

git clone https://github.com/Nikaagh/learnr.git
cd learnr/backend

Create and activate virtual environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies
```
pip install -r requirements.txt
```
Configure environment variables
```
cp .env.example .env
```

Edit .env and set the following:

   DATABASE_URL=postgresql://username:password@localhost:5432/learnr
   SECRET_KEY=your-secret-key-here
   JWT_SECRET_KEY=your-jwt-secret-key-here
   OPENAI_API_KEY=sk-your-openai-api-key-here

Initialize the database
```
flask db upgrade
```

Seed the database (optional)

python scripts/seed_1000_users.py --count 10

Start the backend server
```
python run.py
```

The API will be available at http://localhost:5000

Frontend Setup

Navigate to frontend directory
```
cd frontend
```
Install dependencies
```
npm install
```
Configure environment (optional)
```
cp .env.example .env
```

Edit .env if your backend runs on a different URL:

   VITE_API_URL=http://localhost:5000/api

Start the development server bash npm run dev

The app will be available at http://localhost:3000

Configuration

OpenAI API Key Setup

The student verification feature requires an OpenAI API key:

Visit OpenAI Platform
Sign up or log in to your account
Navigate to the API Keys section
Create a new API key
Add it to your backend/.env file: env OPENAI_API_KEY=sk-proj-...

Database Configuration

For production deployments, update your DATABASE_URL with proper credentials and connection settings:

DATABASE_URL=postgresql://user:password@host:port/dbname?sslmode=require

JWT Token Configuration

Adjust token expiration times in backend/config.py:

Access tokens: 24 hours (development), 1 hour (production recommended)
Refresh tokens: 30 days

Architecture

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Frontend                            │
│                    (React + Vite)                           │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │  Swipe   │  │ Matches  │  │ Messages │  │ Profile  │     │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘     │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │            Socket.IO Client (Real-time)            │     │
│  └────────────────────────────────────────────────────┘     │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │         Axios HTTP Client (REST API)               │     │
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP/WebSocket
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                         Backend                             │
│                    (Flask + Python)                         │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │              Flask-SocketIO Server                 │     │
│  │         (Real-time messaging & events)             │     │
│  └────────────────────────────────────────────────────┘     │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │                REST API Endpoints                  │     │
│  │  /auth  /users  /matches  /messages  /verify       │     │
│  └────────────────────────────────────────────────────┘     │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │          Flask-JWT-Extended (Auth)                 │     │
│  └────────────────────────────────────────────────────┘     │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │          SQLAlchemy ORM + Migrations               │     │
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐      ┌──────────────┐        ┌──────────────┐
│  PostgreSQL  │      │ OpenAI API   │        │  DiceBear    │
│   Database   │      │(GPT-4 Vision)│        │  Avatars     │
└──────────────┘      └──────────────┘        └──────────────┘

Component Architecture

Frontend Components

App.jsx - Main application with routing
Navbar.jsx - Navigation with notification badges
Home.jsx - Landing page
Swipe.jsx - Swipe interface for matching
Matches.jsx - List of matched users
Messages.jsx - Conversations overview
Chat.jsx - Real-time messaging interface
Profile.jsx - User profile management
VerificationUpload.jsx - Student ID verification UI

Backend Services

routes.py - REST API endpoints
socket_events.py - Real-time event handlers
models.py - Database models
auth.py - Authentication logic
config.py - Application configuration

Data Flow

Authentication Flow

User registers/logs in via /api/auth/register or /api/auth/login
Backend validates credentials and generates JWT tokens
Access token stored in localStorage for API requests
Refresh token used to obtain new access tokens
All protected endpoints verify JWT in request headers

Matching Flow

User views candidate profiles on Swipe page
Swipe action sends match preference to backend
Backend creates Match record with swipe type
If mutual match detected, both users notified
Match appears in Matches page for both users

Messaging Flow

User opens chat with matched user
Frontend connects to Socket.IO server
User joins specific chat room via socket
Messages sent via socket, stored in database
Real-time delivery to recipient if online
Offline messages queued for next login
Read receipts updated when messages viewed

Verification Flow

User uploads student ID image from Profile page
Image converted to base64 and sent to backend
Backend calls OpenAI GPT-4 Vision API
AI extracts name and student ID from image
Backend compares with user's registered data
If match, user's is_verified flag set to true
Verification badge displayed on profile

Usage

Creating an Account

Navigate to the registration page
Enter your email, name, student ID, and password
Complete profile setup with bio and courses
Verify your student ID for full access

Verifying Your Student ID

Go to your Profile page
Click on the verification upload section
Upload a clear photo of your student ID
Wait for AI processing (5-10 seconds)
Receive instant verification confirmation

Finding Study Partners

Navigate to the Swipe page
View potential matches based on courses
Swipe right to express interest
Swipe left to pass
When both users swipe right, you match!

Messaging

Go to Matches or Messages page
Click on a matched user to open chat
Send messages in real-time
See typing indicators when they're responding
Receive notifications for new messages

API Documentation

Authentication Endpoints

POST /api/auth/register - Register new user
POST /api/auth/login - Login and receive tokens
POST /api/auth/refresh - Refresh access token

User Endpoints

GET /api/users - List all users
GET /api/users/<id> - Get user by ID
GET /api/profile - Get current user profile
PUT /api/profile - Update current user profile

Match Endpoints

GET /api/swipe/candidates - Get potential matches
POST /api/swipe - Record swipe action
GET /api/matches - Get user's matches

Message Endpoints

GET /api/messages/<user_id> - Get messages with user
GET /api/messages/conversations - Get all conversations
GET /api/messages/unread-count - Get unread message count
POST /api/messages/mark-read/<user_id> - Mark messages as read

Verification Endpoints

POST /api/verify-student-id - Verify student ID with AI

Course Endpoints

GET /api/courses - List all courses
POST /api/courses - Create new course

Troubleshooting

Backend Issues

Port already in use

# Find and kill process on port 5000
lsof -ti:5000 | xargs kill -9

Database connection errors

Verify PostgreSQL is running
Check DATABASE_URL in .env
Ensure database exists and migrations are applied

OpenAI API errors

Verify OPENAI_API_KEY is set correctly
Check API key has sufficient credits
Ensure you're using GPT-4 Vision enabled API

Frontend Issues