UniSphere

A full-stack social networking platform exclusively for NIT Calicut students that helps you find friends based on shared interests and personality compatibility. Built with Flask (Python) backend and Next.js (TypeScript/React) frontend, featuring real-time chat powered by WebSockets and Redis.

🌟 Project Overview

UniSphere is a modern campus networking application designed specifically for NIT Calicut students. It combines personality matching, real-time messaging, and social features to help students connect with like-minded peers. The platform uses questionnaires to match users based on compatibility scores and provides seamless communication through an integrated chat system.

Key Features

🎯 Personality Matching System

• Interactive questionnaire to determine user preferences and personality traits
• Compatibility scoring algorithm to match students with similar interests
• "Find Your Tribe" recommendations based on quiz responses
• View potential friends' profiles with compatibility scores

💬 Real-Time Chat System

• WebSocket-powered messaging for instant communication
• Redis-backed online status tracking (using Upstash Cloud)
• Real-time typing indicators and message status (sent/delivered/read)
• Support for text messages with emoji picker
• Conversation history with persistent storage
• Contact list with online/offline status indicators
• Unread message counters

👤 User Profiles

• Customizable profile with bio, age, gender, hobbies
• Profile picture support (Google OAuth integration)
• Social media links integration (Instagram, WhatsApp, GitHub)
• Activity feed showing user interactions
• "Top Questions" showcase on profiles

🔐 Authentication & Security

• Google OAuth 2.0 integration (restricted to @nitc.ac.in emails)
• JWT token-based authentication
• Secure WebSocket authentication with separate token validation
• Protected routes and API endpoints

📱 Responsive UI/UX

• Modern landing page with campus branding
• Mobile-responsive layout
• Bottom navigation bar for easy mobile access
• Real-time UI updates without page refreshes
• Smooth animations and transitions

⚡ Technical Features

• RESTful API architecture
• WebSocket server with connection pooling
• Redis for distributed state management
• PostgreSQL database with SQLAlchemy ORM
• Database migrations with Alembic
• Concurrent server management (Flask + WebSocket)
• TypeScript for type-safe frontend development

🏗️ Technology Stack

Backend

• Framework: Flask (Python)
• Database: PostgreSQL with SQLAlchemy ORM
• Real-time: WebSocket server (websockets library)
• Cache/State: Redis (Upstash Cloud)
• Authentication:
  • Google OAuth 2.0 (Authlib)
  • JWT tokens (PyJWT)
  • Flask-Login for session management
• Migrations: Alembic
• CORS: Flask-CORS

Frontend

• Framework: Next.js 15 (React 19)
• Language: TypeScript
• Styling: Tailwind CSS
• Icons: React Icons
• WebSocket Client: Native WebSocket API with custom hooks

Infrastructure

• Concurrent Execution: Runs Flask HTTP + WebSocket servers simultaneously
• Virtual Environment: Python venv for dependency isolation
• Package Management: npm for frontend, pip for backend

Getting Started

Prerequisites

• Node.js and npm installed
• Python installed
• Git installed

Installation

1. Clone the repository:

   git clone https://github.com/MUHSIN-M-P/Project-FindMyFriend
   cd frontend

2. Install dependencies for the frontend:

   npm install

3. Install dependencies for the backend (ensure you're in the project root):

   cd backend
   # Recommended: create + activate a virtual environment so installs/runs use the same Python
   python -m venv .venv
   # Windows (PowerShell): .\.venv\Scripts\Activate.ps1
   # Windows (cmd.exe):    .\.venv\Scripts\activate.bat
   # macOS/Linux:          source .venv/bin/activate
   
   python -m pip install -r requirements.txt

Available Scripts

Frontend

• npm run frontend: Runs the Next.js frontend on port 3000.

Backend

• npm run backend:win: Starts the Flask server on Windows using app.py.
• npm run backend:linux: Starts the Flask server on Linux/macOS using app.py.

Full-Stack Development

• npm run dev:win: Runs both the frontend and backend concurrently on Windows.
• npm run dev:linux: Runs both the frontend and backend concurrently on Linux/macOS.

📂 Project Structure

Project-FindMyFriend/
├── backend/                    # Flask Backend
│   ├── app/
│   │   ├── models/            # SQLAlchemy models (User, Message, Conversation)
│   │   ├── routes/            # API routes (auth, chat, websocket)
│   │   ├── services/          # Business logic (AuthService, ChatService)
│   │   ├── utils/             # Utilities (decorators, helpers)
│   │   └── websocket/         # WebSocket implementation
│   │       ├── server.py      # WebSocket server
│   │       ├── client.py      # Connection handler
│   │       ├── service.py     # WebSocket service manager
│   │       └── redis_manager.py # Redis operations
│   ├── migrations/            # Alembic database migrations
│   ├── requirements.txt       # Python dependencies
│   ├── run.py                # Main application entry point
│   └── alembic.ini           # Migration configuration
│
├── frontend/                  # Next.js Frontend
│   ├── src/
│   │   ├── app/              # Next.js app router
│   │   │   ├── chat/         # Real-time chat interface
│   │   │   ├── quiz/         # Personality quiz
│   │   │   ├── profile/      # User profiles
│   │   │   ├── activity/     # Activity feed
│   │   │   ├── settings/     # User settings
│   │   │   └── api/          # API routes (auth, chat)
│   │   ├── components/       # Reusable UI components
│   │   │   ├── Chat_Components/  # Chat-specific components
│   │   │   ├── Navbar.tsx
│   │   │   ├── bottomBar.tsx
│   │   │   └── Usercard.tsx
│   │   └── hooks/            # Custom React hooks
│   │       ├── useAuth.ts    # Authentication hook
│   │       └── useWebSocket.ts # WebSocket connection hook
│   ├── public/               # Static assets
│   │   ├── avatars/          # User avatars
│   │   └── icons/            # UI icons
│   ├── package.json
│   └── next.config.ts        # Next.js configuration
│
└── README.md

🔧 Configuration

Environment Variables

Create a .env file in the backend/ directory:

# Database
DATABASE_URL=postgresql://username:password@localhost/findmyfriend

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# JWT Secret
SECRET_KEY=your_secret_key_for_jwt

# Redis (Upstash)
REDIS_URL=redis://default:password@host:port

# WebSocket
WEBSOCKET_HOST=0.0.0.0
WEBSOCKET_PORT=8765

# Flask
FLASK_ENV=development
FLASK_APP=run.py

🚀 Features in Detail

WebSocket Architecture

The application uses a sophisticated WebSocket implementation for real-time features:

• Separate WebSocket server running on port 8765
• Redis-powered connection management for scalability
• JWT authentication for secure connections
• Automatic reconnection on connection loss
• Online status tracking with TTL-based cleanup
• Message delivery status (sent, delivered, read)
• Typing indicators for active conversations

Chat Features

• Contact list with search functionality
• Conversation threads with message history
• Real-time message delivery
• Emoji picker for expressive messaging
• Unread message badges
• Last seen status for offline users
• Profile quick view from contact list

Matching Algorithm

• Questionnaire-based personality assessment
• Compatibility scoring based on shared interests
• Best match recommendations
• Profile discovery with filtering options

Contributing

Feel free to fork the repository and submit pull requests. For major changes, please open an issue first to discuss the proposed changes.