🎓 RateMyProf India

India's first comprehensive professor and college rating platform with privacy-first anonymous reviews and advanced moderation

Live Platform: Visit RateMyProf.in • API Docs: API Documentation

---

🚀 Quick Start

Start Both Servers (Recommended)

Windows:

start-dev.bat

PowerShell:

.\start-dev.ps1

This will start:

• 🌐 Frontend: http://localhost:3000
• 📡 Backend API: http://localhost:8000
• 📚 API Docs: http://localhost:8000/docs

---

📖 Documentation

Start Here:

1. 📄 EXECUTIVE_SUMMARY.md - One-page project overview
2. 📊 VISUAL_PROJECT_MAP.md - Visual guide with diagrams
3. 📋 PROJECT_STATUS_OVERVIEW.md - Complete detailed status

Technical Documentation:

• SYSTEM_DOCUMENTATION.md - Full architecture
• NEW_FEATURES_DOCUMENTATION.md - Recent features
• PRIORITY_2-5_IMPLEMENTATION_COMPLETE.md - Admin features

---

✨ Key Features

🎓 For Students

• 📊 Dual Rating System
  • Rate professors on multiple dimensions (Overall, Clarity, Helpfulness, Difficulty)
  • Rate colleges on facilities, teaching, opportunities, and more
• 🔒 Privacy-First Anonymous Reviews
  • Submit reviews without revealing your identity
  • Secure mapping tables separate authorship from content
• 🗳️ Community-Driven Voting
  • Upvote/downvote helpful reviews
  • Flag inappropriate content
• ➕ Contribute to Database
  • Add professors not yet listed
  • Add colleges to the platform
• � User Dashboard
  • Manage all your reviews in one place
  • Track your contributions
• 🔍 Smart Search & Filters
  • Find professors by name, department, or college
  • Filter by ratings and review count

🛡️ For Administrators

• 🤖 AI-Powered Content Moderation
  • Automatic profanity detection
  • Spam and low-quality review filtering
  • Sentiment analysis
• 📊 Comprehensive Analytics
  • User activity tracking
  • Review statistics and trends
  • Platform health metrics
• ⚡ Bulk Operations
  • Approve/reject multiple reviews at once
  • Mass user management
• 📧 User Communication
  • Automated notification system
  • Ban/warn users with reasons
  • Handle appeals professionally
• 🔍 Advanced Moderation Tools
  • Review flagging system
  • User activity logs
  • Rate limiting controls

🏛️ For Colleges

• 📈 College Profiles
  • Aggregate ratings across all dimensions
  • Student reviews and feedback
  • Department-wise professor listings
• � Reputation Management
  • Real-time feedback from students
  • Transparent rating system
  • Appeal process for disputed reviews

---

🛠️ Tech Stack

Frontend

• Framework: Next.js 14 with App Router
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: Custom components + Lucide icons
• State Management: React Hooks + Context API
• API Client: Axios
• Authentication: Supabase Auth
• Forms: React Hook Form
• Notifications: React Hot Toast

Backend

• Framework: FastAPI (Python 3.11+)
• API Documentation: OpenAPI/Swagger (auto-generated)
• Validation: Pydantic v2
• Server: Uvicorn with auto-reload
• Authentication: JWT tokens via Supabase
• CORS: Configured for cross-origin requests

Database & Infrastructure

• Database: PostgreSQL (via Supabase)
• Authentication: Supabase Auth
• Storage: Supabase Storage (for future uploads)
• Real-time: Supabase Realtime (potential)
• Row Level Security (RLS): Enabled for privacy

AI/ML & Content Moderation

• Text Analysis: TextBlob (sentiment analysis)
• Profanity Filter: better-profanity
• ML Framework: scikit-learn (spam detection)
• Auto-Flagging: Custom rule-based system

DevOps & Deployment

• Version Control: Git + GitHub
• CI/CD: GitHub Actions
• Frontend Hosting: GitHub Pages (static export)
• Backend Hosting: Railway.app / Render.com (recommended)
• Domain: Custom domain via Namecheap
• SSL/TLS: GitHub Pages auto-SSL

---

📦 Installation & Setup

Prerequisites

• Node.js 18+ and npm 9+
• Python 3.11 or higher
• Git for version control
• Supabase Account (free tier works!)

🚀 Quick Start (Development)

1️⃣ Clone the Repository

git clone https://github.com/NihaallX/ratemyprof.git
cd ratemyprof

2️⃣ Setup Backend

cd backend

# Install dependencies
pip install -r requirements.txt
# or
pip install -e .

# Create environment file
cp .env.example .env

# Edit .env with your credentials:
# - SUPABASE_URL (from Supabase project settings)
# - SUPABASE_SERVICE_ROLE_KEY (from Supabase API settings)
# - ADMIN_USERNAME and ADMIN_PASSWORD

3️⃣ Setup Frontend

cd ../frontend

# Install dependencies
npm install

# Create environment file
cp .env.local.example .env.local

# Edit .env.local with:
# - NEXT_PUBLIC_SUPABASE_URL
# - NEXT_PUBLIC_SUPABASE_ANON_KEY
# - NEXT_PUBLIC_API_URL (http://localhost:8000/v1 for dev)

4️⃣ Setup Database

Run the SQL scripts in your Supabase SQL Editor in this order:

# 1. Create tables
scripts/create_users_table.sql
scripts/create_missing_tables.sql
scripts/create_auto_flagging_tables.sql
scripts/create_user_activities_table.sql
scripts/create_user_communication_tables.sql
scripts/create_college_review_author_mappings.sql
scripts/create_college_review_moderation_tables.sql

# 2. Migrate to anonymous reviews (if upgrading)
scripts/migrate_to_anonymous_reviews.sql

Or use the Python setup script:

python backend/setup_database.py

5️⃣ Start Development Servers

Option A: Both servers at once (Recommended)

# Windows
start-dev.bat

# PowerShell
.\start-dev.ps1

Option B: Separate terminals

# Terminal 1 - Backend
cd backend
uvicorn src.main:app --reload --port 8000

# Terminal 2 - Frontend  
cd frontend
npm run dev

Access the application:

• 🌐 Frontend: http://localhost:3000
• 📡 Backend API: http://localhost:8000/v1
• 📚 API Docs: http://localhost:8000/docs
• 🔍 Alternative Docs: http://localhost:8000/redoc

---

🌍 Production Deployment

Frontend Deployment (GitHub Pages)

The frontend is configured for static export and automatic deployment via GitHub Actions.

See detailed guide: GITHUB_PAGES_SETUP.md

Quick Steps:

1. Configure GitHub Pages in repository settings (Source: GitHub Actions)
2. Add secrets: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, NEXT_PUBLIC_API_URL
3. Configure custom domain in Namecheap DNS
4. Push to main branch - auto-deploys!

Backend Deployment (Railway/Render)

⚠️ Important: GitHub Pages cannot host the Python backend. Deploy separately.

Recommended: Railway.app

# 1. Install Railway CLI
npm i -g @railway/cli

# 2. Login
railway login

# 3. Initialize project
railway init

# 4. Deploy backend
cd backend
railway up

# 5. Add environment variables in Railway dashboard
# - DATABASE_URL (Supabase connection string)
# - SUPABASE_URL
# - SUPABASE_SERVICE_ROLE_KEY
# - ADMIN_USERNAME
# - ADMIN_PASSWORD

Alternative: Render.com

1. Connect GitHub repository
2. Create new Web Service
3. Set root directory to backend
4. Set build command: pip install -r requirements.txt
5. Set start command: uvicorn src.main:app --host 0.0.0.0 --port $PORT
6. Add environment variables

After backend deployment:

1. Copy your backend URL (e.g., https://ratemyprof-api.railway.app)
2. Update GitHub secret NEXT_PUBLIC_API_URL to https://your-backend-url/v1
3. Re-deploy frontend (automatic on next push)

Custom Domain Setup

In Namecheap:

• Add A records: 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153
• Add CNAME record: www → NihaallX.github.io

In GitHub:

• Settings → Pages → Custom domain → Enter your domain
• Wait 24-48 hours for DNS propagation
• Enable "Enforce HTTPS"

---

📁 Project Structure

ratemyprof/
├── 📱 frontend/                    # Next.js 14 Application
│   ├── src/
│   │   ├── components/            # React Components
│   │   │   ├── AdminPanel.tsx     # Admin dashboard
│   │   │   ├── CollegeReviewForm.tsx
│   │   │   ├── ReviewSubmissionForm.tsx
│   │   │   ├── UserDropdown.tsx   # "Hey {username}" greeting
│   │   │   └── ...
│   │   ├── contexts/              # React Context Providers
│   │   │   ├── AuthContext.tsx    # Authentication state
│   │   │   └── NotificationContext.tsx
│   │   ├── pages/                 # Next.js Pages
│   │   │   ├── auth/              # Login, Signup, Verify
│   │   │   ├── professors/[id].tsx # Professor details
│   │   │   ├── colleges/[id].tsx  # College details
│   │   │   ├── admin.tsx          # Admin panel
│   │   │   ├── profile.tsx        # User profile
│   │   │   ├── my-reviews.tsx     # User's reviews
│   │   │   ├── privacy.tsx        # Legal pages
│   │   │   ├── terms.tsx
│   │   │   └── ...
│   │   ├── services/              # API Client Layer
│   │   │   └── api.ts
│   │   └── lib/
│   │       └── supabase.ts        # Supabase client
│   ├── public/                    # Static Assets
│   │   └── .nojekyll              # GitHub Pages config
│   ├── next.config.js             # Next.js configuration
│   ├── tailwind.config.js         # Tailwind CSS config
│   └── package.json
│
├── 🐍 backend/                     # FastAPI Application
│   ├── src/
│   │   ├── api/                   # API Endpoints
│   │   │   ├── auth.py            # Authentication
│   │   │   ├── professors.py      # Professor CRUD
│   │   │   ├── professors_simple.py # Simplified APIs + Bayesian ranking
│   │   │   ├── colleges.py        # College CRUD
│   │   │   ├── reviews.py         # Professor reviews (fixed RLS)
│   │   │   ├── college_reviews.py # College reviews (mapping table)
│   │   │   ├── moderation.py      # Content moderation
│   │   │   ├── college_review_moderation.py # College review moderation
│   │   │   └── user_limits.py     # Rate limiting
│   │   ├── models/                # Pydantic Models
│   │   │   ├── review.py
│   │   │   ├── college_review.py
│   │   │   ├── professor.py
│   │   │   ├── college.py
│   │   │   └── user.py
│   │   ├── services/              # Business Logic
│   │   │   ├── content_filter.py  # AI content filtering
│   │   │   ├── auto_flagging.py   # Auto-flag system
│   │   │   └── user_communication.py
│   │   ├── lib/                   # Utilities
│   │   │   ├── database.py        # Supabase clients
│   │   │   ├── auth.py            # JWT verification
│   │   │   ├── bayesian_ranking.py # Advanced ranking algorithm
│   │   │   ├── cache.py           # Response caching
│   │   │   ├── rate_limiting.py   # Rate limiting
│   │   │   ├── notification_events.py # Event system
│   │   │   └── notification_templates.py # Email templates
│   │   └── main.py                # FastAPI App Entry
│   ├── tests/                     # Test Suite
│   │   ├── test_bayesian_ranking.py # Ranking algorithm tests
│   │   └── ...
│   ├── scripts/                   # Database scripts
│   └── pyproject.toml             # Python dependencies
│
├── 📜 scripts/                     # Database Setup Scripts
│   ├── create_users_table.sql
│   ├── create_college_review_author_mappings.sql
│   ├── create_auto_flagging_tables.sql
│   ├── create_user_activities_table.sql
│   ├── create_user_communication_tables.sql
│   ├── migrate_to_anonymous_reviews.sql
│   └── ...
│
├── 🔧 .github/
│   └── workflows/
│       ├── ci.yml                 # CI/CD pipeline
│       └── deploy-github-pages.yml # Auto-deployment
│
├── 📝 Documentation
│   ├── README.md                  # This file!
│   ├── GITHUB_PAGES_SETUP.md      # Deployment guide
│   ├── SYSTEM_DOCUMENTATION.md    # Architecture
│   ├── NEW_FEATURES_DOCUMENTATION.md
│   └── ...
│
├── start-dev.bat                  # Windows dev server launcher
├── start-dev.ps1                  # PowerShell dev launcher
└── .gitignore

Key Files Explained

Frontend:

• next.config.js - Configured for static export (output: 'export')
• src/components/UserDropdown.tsx - Shows "Hey {username}" greeting
• src/components/CollegeReviewForm.tsx - Fixed data structure for nested ratings
• src/pages/auth/* - Complete authentication flow

Backend:

• src/api/reviews.py - Uses supabase_admin client to bypass RLS
• src/api/college_reviews.py - Anonymous reviews with mapping table
• src/services/content_filter.py - AI-powered moderation
• src/lib/database.py - Exports both supabase (anon) and supabase_admin clients

Database:

• review_author_mappings - Maps professor reviews to authors (privacy)
• college_review_author_mappings - Maps college reviews to authors
• Both tables have RLS policies allowing only service role access

---

🧪 Testing

Backend Tests

cd backend

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_reviews.py

# Run with verbose output
pytest -v

Frontend Tests

cd frontend

# Run unit tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

# Run E2E tests with Playwright
npm run test:e2e

# Run E2E with UI
npm run test:e2e:ui

Manual Testing

# Test review submission flow
python backend/test_review_submit.py

# Test content filter
python backend/test_content_filter.py

# Test admin login
python backend/test_admin_login.py

---

🏗️ Architecture Highlights

Privacy-First Anonymous Reviews

User submits review
  ↓
1. Insert review (NO user_id) → Get UUID
  ↓
2. Insert mapping (review_id + author_id) in private table
  ↓
3. If mapping fails → Delete review (rollback)
  ↓
✅ Review is public, authorship is private

Key Implementation:

• Reviews table has NO user_id column (fully anonymous)
• Separate *_author_mappings tables store authorship
• Only service role (backend) can access mapping tables
• RLS policies prevent users from seeing other authors
• Users can still manage their own reviews via mapping

Authentication Flow

1. User signs up → Supabase Auth creates user
2. User logs in → Receives JWT token
3. Token stored in localStorage (frontend)
4. Every API request includes: Authorization: Bearer <token>
5. Backend verifies token via Supabase
6. Grants/denies access based on user role

Content Moderation Pipeline

Review Submitted
  ↓
1. Profanity Filter (better-profanity)
  ↓
2. Sentiment Analysis (TextBlob)
  ↓
3. Spam Detection (ML classifier)
  ↓
4. Auto-flag if suspicious
  ↓
5. Admin review if flagged
  ↓
6. Publish if approved

---

📊 Current Status

Component	Status	Progress
🎓 Professor Reviews	✅ Complete
🏛️ College Reviews	✅ Complete
🔐 Authentication	✅ Complete
🛡️ Content Moderation	✅ Complete
👥 Admin Panel	✅ Complete
📊 Analytics	✅ Complete
🎯 Bayesian Ranking	✅ Complete
🌙 Dark Mode	✅ Complete
🧪 Testing	⚠️ In Progress
📝 Documentation	✅ Complete
🚀 Deployment	⚠️ In Progress

Overall Project Status: 🟢 Production Ready - 92% Complete

Recent Updates (Latest First)

November 25, 2025:

• ✅ Bayesian Ranking System - Implemented sophisticated ranking algorithm for professors
  • Balances rating quality (avg_rating) and quantity (total_reviews)
  • Formula: score = (C × global_mean + reviews × rating) / (C + reviews)
  • Prevents gaming: 1 perfect review can't outrank 50 reviews at 4.8
  • Optional recency weighting with exponential decay
  • Configurable confidence parameter (default C=10)
  • Comprehensive test suite with 6 test cases (all passing)
  • See backend/src/lib/BAYESIAN_RANKING_README.md for details
• ✅ Dark Mode Support - Added complete dark mode styling to college reviews section
  • Rating categories grid, review cards, and all text elements
  • Smooth transitions and proper contrast
  • Uses Tailwind's dark: classes
• ✅ API Improvements - Fixed validation errors and reduced limit to 200 (from 1000)
• ✅ Frontend Build - Successfully built and deployed with all dependencies

October 20, 2025:

• ✅ Configured GitHub Pages deployment with custom domain support
• ✅ Updated Next.js config for static export
• ✅ Created comprehensive deployment documentation
• ✅ Added .nojekyll for GitHub Pages compatibility

Earlier Updates:

• ✅ Fixed review submission (RLS bypass with admin client)
• ✅ Created college review system with anonymous mapping
• ✅ Added "Hey {username}" greeting to UI
• ✅ Built complete authentication pages (login, signup, verify)
• ✅ Created legal compliance pages (DPDP Act, Privacy, Terms)
• ✅ Developed admin panel with moderation tools
• ✅ Implemented AI-powered content filtering
• ✅ Added review voting and flagging system

---

🎯 Roadmap

✅ Phase 1: Core Platform (COMPLETE)

• Database schema design
• Backend API development
• Frontend UI/UX
• Professor rating system
• College rating system
• User authentication
• Anonymous review system

✅ Phase 2: Moderation & Safety (COMPLETE)

• Admin authentication
• Content filtering (profanity, spam)
• Auto-flagging system
• Review moderation dashboard
• User management
• Appeals system

🚧 Phase 3: Deployment & Launch (IN PROGRESS)

• GitHub Actions CI/CD
• Frontend deployment (GitHub Pages)
• Backend deployment (Railway/Render)
• Custom domain configuration
• SSL/HTTPS setup
• Performance optimization
• Security audit

📋 Phase 4: Beta Testing (UPCOMING)

• Invite beta users
• Gather feedback
• Fix bugs and issues
• Optimize performance
• Improve UX based on feedback

🚀 Phase 5: Public Launch (PLANNED)

• Marketing campaign
• Social media presence
• SEO optimization
• Analytics setup (Google Analytics)
• Error monitoring (Sentry)
• User onboarding flow

🔮 Future Enhancements

• Mobile app (React Native)
• Advanced search (Elasticsearch/Algolia)
• Email notifications
• AI review summarization
• Multi-language support (Hindi, etc.)
• Course reviews
• Professor comparison tool
• College comparison tool
• Verified student badges
• Premium features for colleges

---

🤝 Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, or documentation improvements.

How to Contribute

1. Fork the repository

   # Click "Fork" on GitHub, then clone your fork
   git clone https://github.com/YOUR-USERNAME/ratemyprof.git
   cd ratemyprof

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Write clean, readable code
   • Follow existing code style
   • Add tests if applicable
   • Update documentation

4. Test your changes

   # Backend tests
   cd backend && pytest
   
   # Frontend tests
   cd frontend && npm test

5. Commit with clear messages

   git add .
   git commit -m "feat: Add amazing feature"
   
   # Use conventional commits:
   # feat: New feature
   # fix: Bug fix
   # docs: Documentation
   # style: Formatting
   # refactor: Code restructuring
   # test: Adding tests
   # chore: Maintenance

6. Push and create Pull Request

   git push origin feature/amazing-feature

   Then open a PR on GitHub with:

   • Clear title and description
   • Screenshots (if UI changes)
   • Link to related issue (if applicable)

Development Guidelines

• Code Style: Follow PEP 8 (Python), Airbnb style guide (TypeScript)
• Testing: Add tests for new features
• Documentation: Update README and inline comments
• Commits: Use conventional commit messages
• PRs: One feature per PR, keep them focused

Areas We Need Help

• 🧪 Testing: Increase test coverage
• 📱 Mobile: React Native app development
• 🌐 Translations: Hindi and regional language support
• 🎨 Design: UI/UX improvements
• 📝 Documentation: Tutorials and guides
• 🐛 Bug Fixes: Check open issues

---

🐛 Bug Reports & Feature Requests

Found a Bug?

1. Check if it's already reported in Issues
2. If not, create a new issue with:
   • Clear title
   • Steps to reproduce
   • Expected vs actual behavior
   • Screenshots/logs if applicable
   • Your environment (OS, browser, etc.)

Have a Feature Idea?

1. Check Discussions
2. Create a new discussion with:
   • Problem you're trying to solve
   • Proposed solution
   • Alternative approaches considered
   • Mockups/examples if applicable

---

� License

This project is licensed under the MIT License - see the LICENSE file for details.

What this means:

• ✅ Commercial use allowed
• ✅ Modification allowed
• ✅ Distribution allowed
• ✅ Private use allowed
• ⚠️ Liability and warranty not provided

---

👥 Team & Contact

Project Team

• Creator & Lead Developer: NihaallX
• Repository: github.com/NihaallX/ratemyprof
• Current Branch: 001-ratemyprof-india-platform
• Contributors: See all contributors

Get in Touch

• 🌐 Website: [Your Domain Here]
• 📧 Email: [Contact Email]
• � Discussions: GitHub Discussions
• � Bug Reports: GitHub Issues
• 📱 Social Media: [Links to be added]

Support & Help

• Documentation: Start with this README, then see SYSTEM_DOCUMENTATION.md
• Deployment Guide: GITHUB_PAGES_SETUP.md
• Feature Docs: NEW_FEATURES_DOCUMENTATION.md
• Community: Join GitHub Discussions for questions

---

🙏 Acknowledgments

Built For

Indian Universities - Starting with Vishwakarma University (VU) Pune

Special Thanks

• All beta testers and early users
• Contributors to open-source dependencies
• Supabase for excellent BaaS platform
• Next.js team for amazing React framework
• FastAPI team for amazing Python framework

Compliance

This platform complies with:

• 🇮🇳 Digital Personal Data Protection Act (DPDP) 2023
• 📜 Information Technology Act, 2000
• 🔒 Privacy by Design principles

---

📚 Additional Resources

Documentation

• 📖 Executive Summary - One-page overview
• 🗺️ Visual Project Map - Architecture diagrams
• 📊 Project Status - Detailed status
• 🏗️ System Documentation - Full technical docs
• ✨ New Features - Feature documentation
• 🚀 Deployment Guide - Deploy to production
• 🔧 Admin Panel Guide - Admin features

Related Projects

• Supabase - Backend as a Service
• Next.js - React Framework
• FastAPI - Python Web Framework
• Tailwind CSS - Utility-first CSS

---

🌟 Star History

If you find this project helpful, please consider giving it a star! ⭐

---

📈 Project Stats

---

Made with need for Indian Education

Empowering students to make informed decisions about their education

---

🔗 Quick Links

🏠 Home • 📖 Docs • ✨ Features • 🚀 Deploy • 🤝 Contribute • 💬 Discussions

---

⭐ Star us on GitHub — it helps!

Report Bug • Request Feature • Ask Question

---

© 2025 RateMyProf India. Built with ❤️ by the community.