Skip to content

README.md

Latest commit

 

History

History
199 lines (159 loc) · 10.3 KB

README.md

File metadata and controls

199 lines (159 loc) · 10.3 KB
Raw

OppLens

Live Demo

📘 View Complete System Design Document (HLD, LLD, Database Schema, Tech Stack)

OppLens is a modern, full-stack platform designed to connect developers through tech events. It goes beyond simple CRUD, offering an intelligent, personalized, and highly interactive experience for discovering, hosting, and managing developer meetups and hackathons. It leverages a robust microservices architecture for data aggregation and machine learning-powered recommendations.

🚀 Engineering Impact & Scale

  • Async ETL & Reverse-Engineering: Engineered a fault-tolerant Python/FastAPI scraping pipeline utilizing Playwright and reverse-engineered JSON APIs to ingest 5,000+ opportunities across 5 platforms.
  • Deduplication Engine: Utilized composite-key hashing to eliminate ~95% of redundant database writes (~1,000+ duplicate payloads/week), reducing database bloat and ensuring pristine training data for downstream ML models.
  • NLP Recommendation Engine: Developed a hybrid recommendation engine (TF-IDF + Cosine Similarity). Offloaded semantic matching to MongoDB Atlas Vector Search (HNSW indexes), reducing query complexity from O(N) to O(log N) for <50ms personalized feed generation.
  • Distributed Caching (Redis): Optimized API read throughput by implementing a Redis caching layer with targeted invalidation policies, dropping p95 ML inference response times from 400ms to <80ms.

🧠 System Architecture

graph TD
    subgraph Frontend [Next.js 15 Application]
        UI[React User Interface]
        SA[Server Actions]
        Auth[Auth.js]
    end

    subgraph Backend [Python / FastAPI Microservice]
        API[FastAPI Router]
        ML[TF-IDF Recommendation Engine]
        Scraper[Async Scraper Pipeline]
        Cron[APScheduler]
    end

    subgraph ExternalPlatforms [External Platforms]
        Dev[Devfolio]
        Unstop[Unstop]
        HE[HackerEarth API]
        MLH[MLH]
        HR[HackerRank]
    end

    subgraph Database
        Mongo[(MongoDB Atlas)]
        VS[Atlas Vector Search]
    end
    
    subgraph Cache
        Redis[(Redis Cache)]
    end

    %% Connections
    UI <-->|Concurrent Promise.all| SA
    SA <-->|Fetch /recommend| API
    SA <-->|CRUD Operations| Mongo
    
    API <--> Redis
    API <--> ML
    ML <--> VS
    
    Cron -->|Triggers| Scraper
    Scraper -->|Graceful Degradation| ExternalPlatforms
    Scraper -->|Upsert Deduplicated Data| Mongo
Loading

Key Features

Authentication and Authorisation

security is handled via Next-Auth v5, implementing a robust, role-aware authentication system.

  • Multi-Provider Login: Supports OAuth sign-in via GitHub and Google, as well as traditional Email/Password credentials. Screenshot 2026-01-04 233825 Screenshot 2026-01-04 233844
  • Session Management: Uses secure, encrypted sessions to persist user state across the application.
  • Protected Routes: Middleware and server-side checks ensure that private pages (like /create-event or /profile) are inaccessible without a valid session.

Event System Integrity & Concurrency

-Create,Update,Delete and Share Events : allows adding date,time,venue,agenda,EventImage,tags,NumberOfSeats,Overview to manage events image image image

  • Atomic Booking Engine: Engineered a race-condition-free booking system using MongoDB Atomic Operations ($inc, $expr). This prevents overselling by handling capacity checks and updates in a single, indivisible database transaction. image
image
  • Smart Inventory Management: Real-time "Sold Out" and "Almost Full" states are enforced at the database level, ensuring 100% data consistency even under high-concurrency load. image

Intelligence & Personalization

  • Smart Recommendation Engine: A hybrid NLP recommendation engine (TF-IDF + Cosine Similarity + Collaborative Filtering) curating a "For You" sidebar, served in <50ms via our Python microservice. It leverages MongoDB Atlas Vector Search for high-dimensional embedding matching. image

  • Time-Aware Feed: The homepage intelligently separates "Happening Soon" (Urgent) events from general discovery, adapting to the user's local time.

  • Dynamic Greetings: Personalized welcome messages that change based on the time of day.

image

The Attendee Experience : allows better Developer Experience to user while sharing events on other platforms like X, whatsapp , Meta, and others

  • Dynamic Social Cards: Automated Open Graph (OG) image generation ensures every event link shared on Twitter/LinkedIn looks professional with dynamic titles and dates. image

Professional Identity

  • Developer Profiles: A comprehensive profile system acting as a mini-portfolio, showcasing the user's bio, institution, location, GitHub/Portfolio links, and confirmed event schedule. Screenshot 2025-12-30 130822 Screenshot 2025-12-30 130840 Screenshot 2025-12-29 125951

Performance & UX

  • Frontend Parallelization: Eradicated sequential data-fetching waterfalls using Promise.all(), reducing load times by ~300% and achieving a 98/100 Lighthouse performance score.

  • Optimistic Bookmarking: Implemented React 19's useOptimistic hook to provide a zero-latency "Save for Later" experience, ensuring the UI updates instantly while the server processes in the background.

  • Client-Side Validation: Instant file size checks (4MB limit) prevents unnecessary server load and improves upload UX. image

  • Skeleton Loading: Custom shimmer effects preventing layout shifts (CLS) during data fetching. Screenshot 2026-01-04 234721

🛠️ Tech Stack

  • Frontend: Next.js 15 (App Router), React 19, Tailwind CSS, Lucide React
  • Backend (Node): Next.js API Routes, NextAuth.js, Mongoose ODM
  • Backend (Python): FastAPI, Uvicorn, Scikit-Learn, Playwright, BeautifulSoup4
  • Search & ML: Elasticsearch, MongoDB Atlas Vector Search (HNSW), TF-IDF
  • Caching: Redis
  • Database: MongoDB Atlas
  • DevOps: Docker, Render, Vercel, APScheduler

🏁 Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

  • Node.js (v20 or later)
  • npm
  • A MongoDB database instance
  • Redis (optional, for caching)

Installation

  1. Clone the repository:

    git clone https://github.com/manaskng/Dev-Event_Sync.git

  2. Navigate to the Next.js project directory:

    cd Dev-Event_Sync/my-app

  3. Install dependencies:

    npm install

  4. Set up environment variables: Create a .env.local file in the root of the my-app project and add the following variables.

    # Database
MONGODB_URI=your_mongodb_connection_string

# Auth (Generate with `openssl rand -base64 32`)
AUTH_SECRET=your_next_auth_secret
# OAuth Providers
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
# Image Storage
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
# Base URL (Set to your Vercel URL in production)
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Analytics (Optional)
NEXT_PUBLIC_POSTHOG_KEY=your_key

  5. Run the development server:

    npm run dev

    Open http://localhost:3000 in your browser to see the result.

  6. Start the Python Recommendation Microservice:

    cd ../recommendation-service
python -m venv venv
# On Windows: .\venv\Scripts\activate
# On Mac/Linux: source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

📂 Project Structure

  • my-app/app/: Next.js 15 App Router structure.
  • my-app/(auth)/: Login/Register logic.
  • my-app/events/: Event details, creation, and editing flows.
  • my-app/profile/: User dashboard and settings.
  • my-app/components/: Reusable UI components (EventCard, TicketCard, etc.).
  • my-app/database/: Mongoose schemas for User, Event, and Booking.
  • my-app/lib/actions/: Server Actions responsible for all data mutations.
  • recommendation-service/: Python microservice for web scraping and ML recommendations.

Built with ❤️ by Manas Raj