learnr

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

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.

• 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

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

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

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

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

• 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)

• 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

• 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

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

1. Clone the repository

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

2. Create and activate virtual environment

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

3. Install dependencies

   pip install -r requirements.txt

4. 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

5. Initialize the database

   flask db upgrade

6. Seed the database (optional)

   python scripts/seed_1000_users.py --count 10

7. Start the backend server

   python run.py

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

1. Navigate to frontend directory

   cd frontend

2. Install dependencies

   npm install

3. Configure environment (optional)

   cp .env.example .env

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

   VITE_API_URL=http://localhost:5000/api

4. Start the development server

   npm run dev

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

The student verification feature requires an OpenAI API key:

1. Visit OpenAI Platform
2. Sign up or log in to your account
3. Navigate to the API Keys section
4. Create a new API key
5. Add it to your backend/.env file:

   OPENAI_API_KEY=sk-proj-...

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

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

Adjust token expiration times in backend/config.py:

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

┌─────────────────────────────────────────────────────────────┐
│                         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     │
└──────────────┘      └──────────────┘        └──────────────┘

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

Authentication Flow

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

Matching Flow

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

Messaging Flow

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

Verification Flow

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

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

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

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

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

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

• 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

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

• 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

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

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

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

Port already in use

# Change port in vite.config.js or use different port
npm run dev -- --port 3001

Socket connection fails

• Verify backend is running
• Check CORS settings in backend
• Ensure Socket.IO client version matches server

Token expiration issues

• Tokens refresh automatically on 401 errors
• Clear localStorage if issues persist
• Check JWT configuration in backend

This is a hackathon project, but we welcome feedback and ideas! Feel free to open an issue or reach out to the team.

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

License information coming soon.

This is our first hackathon project together. Brought to you with ❤️ by BASE2:

• Nika - @Nikaagh
• Ismael - @TheBarzani