Skip to content
BranchesTags

Repository files navigation

🚀 Campus Connect

The Next-Gen Real-Time Student Discovery & Networking Ecosystem

License: MIT React Vite Tailwind CSS Firebase Three.js

Campus Connect is not just another student directory — it is a high-performance, real-time, campus-exclusive social ecosystem engineered for university students to discover peers, collaborate on research, participate in campus events, check in via QR tokens, and communicate securely.

Designed with modern glassmorphic aesthetics, WebGL shader lighting, real-time Firestore listeners, dynamic location density mapping, and a strict two-tier verification model.

📋 Table of Contents

✨ Key Features

  • 🛡️ Campus Gatekeeper & ID Card Verification
    Restricted access strictly bound to verified university registration numbers in valid_students combined with Student ID Card photo verification to prevent unauthorized external sign-ups.

  • ⚡ Real-Time Admin Session Kill Switch
    Integrated Firestore listener instantly revokes active student sessions and logs out users in real time if access status is modified by campus administration.

  • 📱 QR-Code Physical Event Check-In Engine
    Club leaders generate time-boxed check-in QR codes (checkins/{activityId}). Volunteers scan the code via live camera scanner to convert tentative sign-ups into verified event attendance.

  • 🏆 Community Volunteer Leaderboard & Duty Reviews
    Real-time leaderboard ranking student volunteers by verified completed operations (completedOps). Includes mission assignment, task review submission, and lead approval workflows.

  • 🗺️ Adaptive Location Density Mapping
    Real-time interactive map (LocationTracking.jsx) with dynamic auto-centering and zoom calculations aligned towards active student density on campus.

  • 🎓 Seniority Filtering (Junior vs Senior)
    Smart student directory filtering by batch, department, and academic seniority (Senior vs Junior levels).

  • 🏫 College-Wise Campus Ecosystem Scoping
    Multi-campus ecosystem isolation enabling students to experience their distinct college culture while enabling discovery.

  • 🃏 Interactive Discovery Stack
    Swipeable card stack supporting dual discovery modes:

    • Social Mode: Swipe to discover peers filtered by department, batch, and interest tags.
    • Volunteer Mode: Explore and volunteer for campus activities, community events, and drives.

  • 💬 Real-Time Direct & Ephemeral Group Chat Engine
    Instant 1-on-1 private messaging and temporary group chat rooms with 1-hour automated expiration logic and online presence indicators (isOnline & lastSeen).

  • 🚩 Campus Moderation & Reporting Shield
    Comprehensive safety suite allowing users to block or report toxic behavior, persisting directly into Firestore reports and blocks collections.

  • 🌌 Futuristic Glassmorphic WebGL UI
    Ultra-dark futuristic design featuring OGL / Three.js light ray shaders, responsive drawer navigation, custom cursors, and liquid transitions.

🏗️ System Architecture & Flowcharts

1. High-Level Architecture

graph TD
    User(["Student / User Browser"]) -->|"HTTP / WebGL"| Frontend["React + Vite Frontend"]
    
    subgraph FrontendApp ["Frontend Application Layer"]
        Frontend --> Router["React Router v6"]
        Router --> Context["Auth & Main Context API"]
        Context --> UIComponents["Pages & Glassmorphic UI Components"]
        UIComponents --> Shaders["WebGL LightRays / Three.js Engine"]
        UIComponents --> QRScanner["HTML5 QR Camera Scanner"]
    end

    subgraph FirebaseInfra ["Firebase Cloud Infrastructure"]
        Context -->|"Auth API"| FBAuth["Firebase Authentication"]
        Context -->|"Real-Time Listeners & CRUD"| Firestore[("Cloud Firestore NoSQL")]
        UIComponents -->|"Asset & ID Card Storage"| FBStorage["Firebase Storage"]
    end

    subgraph SecurityLayer ["Security & Access Layer"]
        Firestore --> SecurityRules["Firestore Rules v2"]
        SecurityRules -->|"Validation"| ValidStudents[("valid_students Collection")]
        SecurityRules -->|"QR Verification"| CheckinsCol[("checkins Collection")]
    end
Loading

2. Gatekeeper Authentication & Kill-Switch Flow

sequenceDiagram
    autonumber
    actor Student as Student Client
    participant AuthUI as Login / Signup UI
    participant Service as AuthService
    participant Firestore as Cloud Firestore
    participant FBAuth as Firebase Auth
    participant Admin as Admin / Listener

    Student->>AuthUI: Enters Email, Password, RegNo & Uploads ID Card
    AuthUI->>Service: registerStudent(email, password, regNo, idCard)
    Service->>Firestore: Check valid_students record for RegNo
    
    alt RegNo Not Found or Linked to Different Email
        Firestore-->>Service: Invalid / Unauthorized
        Service-->>AuthUI: Throw Registration Error
        AuthUI-->>Student: Display Error Notification
    else RegNo Validated
        Service->>FBAuth: createUserWithEmailAndPassword()
        FBAuth-->>Service: Auth Tokens & User Credential
        Service->>Firestore: Update valid_students: is_registered = true
        Service->>Firestore: Create user profile with ID Card & initial status
        Service-->>AuthUI: Auth Success
        AuthUI-->>Student: Redirect to /discover
    end

    note over Student, Firestore: Real-Time Session Kill Switch Listener
    Admin->>Firestore: Set valid_students record is_registered = false
    Firestore-->>Student: Real-time onSnapshot Triggered
    Student->>Student: Display "Session Revoked by Admin!" Banner
    Student->>FBAuth: Trigger automatic logout & Redirect to /login
Loading

3. QR-Code Attendance Verification Flow

sequenceDiagram
    autonumber
    actor Leader as Club Leader
    actor Volunteer as Student Volunteer
    participant Dashboard as ClubLeadDashboard
    participant Discovery as Discovery Page
    participant Firestore as Cloud Firestore

    Leader->>Dashboard: Click "Generate Check-in QR"
    Dashboard->>Firestore: Create checkins/{activityId} (token, expiresAt)
    Dashboard-->>Leader: Render visual QR Code (token URL)
    
    Volunteer->>Discovery: Open "Scan Check-In QR" Modal
    Volunteer->>Discovery: Scan QR Code via Live Camera
    Discovery->>Firestore: Read checkins/{activityId} & validate token

    alt Token Expired or Invalid
        Firestore-->>Discovery: Token Invalid / Expired
        Discovery-->>Volunteer: Show Error: "Check-in expired or invalid"
    else Token Validated
        Firestore->>Firestore: Add Volunteer UID to activities.verified_attendees
        Firestore->>Firestore: Increment User completedOps count (+1)
        Firestore-->>Discovery: Check-in Verified!
        Discovery-->>Volunteer: Display "Attendance Verified (+1 Op)" Badge
    end
Loading

4. Real-Time Messaging & Ephemeral Chat Flow

flowchart LR
    subgraph ClientA ["Student A"]
        A1["Select Peer / Group"] --> A2["Send Message"]
    end

    subgraph FirestoreBackend ["Firestore Backend"]
        B1[("chats Collection")]
        B2[("chats/chatId/messages Subcollection")]
    end

    subgraph ClientB ["Student B"]
        C1["Live onSnapshot Listener"] --> C2["Render Chat Bubble & Presence"]
    end

    subgraph ExpiryWorker ["Expiry Worker"]
        E1["Check expiresAt Timestamp"] -->|"If Current Time > expiresAt"| E2["Filter / Purge Ephemeral Room"]
    end

    A2 -->|"sendMessage service"| B2
    A2 -->|"updateDoc lastMessage"| B1
    B2 -->|"Real-Time Push"| C1
    B1 --> ExpiryWorker
Loading

🗄️ Database Schema & Data Models

Campus Connect operates under a two-tier security model in Cloud Firestore:

1. valid_students (Admin Access Control)

{
  "registrationNumber": "241001001218",
  "email": "student@university.edu",
  "is_registered": true,
  "lastLogin": "Timestamp"
}

2. users (Student Profiles)

{
  "uid": "firebase_auth_uid",
  "name": "Anirban Sarkar",
  "regNo": "241001001218",
  "branch": "CSE",
  "batch": "2024-28",
  "seniority": "Senior",
  "college": "Institute of Engineering & Management",
  "bio": "Coder / Innovator / Troubleshooter",
  "interests": ["Coding", "AI-ML", "Physics"],
  "role": "student",
  "photoUrl": "https://...",
  "idCardUrl": "https://...",
  "completedOps": 5,
  "isOnline": true,
  "lastSeen": "Timestamp",
  "location": {
    "lat": 22.5726,
    "lng": 88.4337
  },
  "updatedAt": "Timestamp"
}

3. checkins (QR Code Attendance Tokens)

{
  "token": "a8f9c2d1-e4b5-4a6c-9d8e-1f2a3b4c5d6e",
  "expiresAt": "Timestamp (Event end time or +2 hours)",
  "createdBy": "lead_uid",
  "activityId": "activity_document_id"
}

4. activities (Club & Community Events)

{
  "activityId": "auto_generated_id",
  "event_title": "Campus AI Hackathon",
  "community_name": "Coding Club",
  "description": "Building next-gen AI tools",
  "event_date": "2026-10-15",
  "image_url": "https://...",
  "volunteer_list": ["uidA", "uidB"],
  "verified_attendees": ["uidA"],
  "created_by": "lead_uid"
}

5. chats (Direct & Group Conversations)

{
  "chatId": "uidA_uidB",
  "type": "group | ephemeral_group",
  "groupName": "Hackathon Squad",
  "users": ["uidA", "uidB", "uidC"],
  "createdBy": "uidA",
  "admins": ["uidA"],
  "lastMessage": "Let's meet at 5 PM!",
  "createdAt": "Timestamp",
  "updatedAt": "Timestamp",
  "expiresAt": "Timestamp (1 Hour from creation)"
}

Subcollection: chats/{chatId}/messages

{
  "messageId": "auto_generated_id",
  "senderId": "uidA",
  "text": "Hey everyone!",
  "createdAt": "Timestamp"
}

6. reports & blocks (Safety & Moderation)

// reports/{reportId}
{
  "reporterId": "uidA",
  "reportedUserId": "uidB",
  "reason": "Harassment / Spam",
  "details": "Inappropriate messages in group chat",
  "createdAt": "Timestamp"
}

// blocks/{blockId}
{
  "blockerId": "uidA",
  "blockedUserId": "uidB",
  "createdAt": "Timestamp"
}

🛠️ Tech Stack

Frontend Core

  • ⚛️ React 18.3 — Functional components, custom hooks, and Context API architecture.
  • ⚡ Vite 7.2 — Instant Hot Module Replacement (HMR) and optimized ESbuild pipelines.
  • 🚦 React Router v6 — Declarative client-side routing & protected route wrappers.

Styling & UI Design

  • 🎨 Tailwind CSS v4 — Utility-first engine with high-performance CSS @theme variables.
  • 💫 Framer Motion 12 — Smooth layout transitions and interactive card animations.
  • 🎨 Lucide React — Crisp icon library.
  • 📷 HTML5-QRCode — Web-based live camera scanner for QR verification.

Shaders & WebGL Graphics

  • 🧊 Three.js — 3D graphics rendering engine.
  • ⚡ OGL (Minimal WebGL) — Custom GPU light ray background shader (LightRays.jsx).

Backend (BaaS) & Database

  • 🔥 Firebase Authentication — Secure email/password auth.
  • 📦 Cloud Firestore — Real-time NoSQL document store with live snapshot sync.
  • 💾 Supabase JS Client — Auxiliary database integration option.
  • 🐍 FastAPI / Python Admin SDK — Python backend environment for batch verification & administrative scripts.

🔐 Security & Access Control

Firestore enforcement is governed by firestore.rules (rules version 2):

  • Campus Gatekeeper: valid_students collection readable by clients for auth validation.
  • Profile Ownership: users/{userId} documents are only writable by the authenticated owner (request.auth.uid == userId).
  • QR Attendance Verification: checkins/{activityId} documents readable by authenticated volunteers; activities verified attendee updates allowed for signed-in users.
  • Private Messaging Shield: Chat threads (chats/{chatId}) and nested messages (messages/{messageId}) are accessible only to users explicitly included in the resource.data.users array.
  • Moderation Safety: reports and blocks collections writeable by reporting users.

📦 Getting Started & Setup Guide

Prerequisites

  • Node.js: v18.0.0 or higher
  • npm or yarn

1️⃣ Clone the Repository

git clone https://github.com/your-username/campusConnect.git
cd campusConnect

2️⃣ Install Frontend Dependencies

cd frontend
npm install

3️⃣ Configure Environment / Firebase

Verify or update your Firebase configuration parameters in frontend/src/conf/firebase.js:

import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";
import { getFirestore } from "firebase/firestore";
import { getStorage } from "firebase/storage";

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_PROJECT_ID.appspot.com",
  messagingSenderId: "YOUR_SENDER_ID",
  appId: "YOUR_APP_ID"
};

const app = initializeApp(firebaseConfig);
export const auth = getAuth(app);
export const db = getFirestore(app);
export const storage = getStorage(app);

4️⃣ Run Development Server

npm run dev

Open your browser at http://localhost:5173.

5️⃣ (Optional) Python FastAPI Backend Setup

# In the repository root
pip install -r requirements.txt

📁 Project Directory Structure

campusConnect/
├── firestore.rules          # Security rules for Cloud Firestore (v2)
├── db.json                  # Local seed / mock database reference
├── requirements.txt         # Python dependencies for admin tools
├── LICENSE                  # MIT License
└── frontend/
    ├── package.json         # Node.js dependencies and scripts
    ├── vite.config.js       # Vite build configuration
    ├── index.html           # Main HTML document entrypoint
    └── src/
        ├── main.jsx         # App entrypoint
        ├── App.jsx          # Routes definition & Protected Route wrapper
        ├── index.css        # Global CSS, theme variables & WebGL canvas reset
        ├── conf/
        │   ├── firebase.js  # Firebase SDK initialization
        │   └── supabase.js  # Supabase client setup
        ├── context/
        │   └── mainContext.jsx # Auth state, profile listener & Kill-Switch logic
        ├── services/
        │   ├── Authservice.js    # Login, signup, logout & online status services
        │   ├── chatService.js    # Direct, group, ephemeral chat & real-time listeners
        │   └── profileService.js # Profile fetch & update methods
        ├── components/
        │   ├── Layout.jsx           # Responsive Navbar & Sidebar shell
        │   ├── Loading.jsx          # Futuristic loading screen
        │   ├── NotificationsPopup.jsx # Real-time alert notifications
        │   ├── BrandLogo.jsx        # Animated brand logo component
        │   ├── LightPillar.jsx      # Dynamic visual effect backdrop pillar
        │   ├── Cards/
        │   │   ├── CardStack.jsx    # Swipeable card container logic
        │   │   ├── ProfileCard.jsx  # Student profile card rendering
        │   │   └── VolunteerCard.jsx# Activity/Volunteer card rendering
        │   ├── auth/
        │   │   ├── LoginUI.jsx      # Login interface
        │   │   └── SignUpUI.jsx     # Registration interface with ID Card upload
        │   └── effects/
        │       ├── LightRays.jsx    # WebGL GPU Light Rays shader canvas
        │       └── LightRays.css    # Shader layout styling
        └── pages/
            ├── LandingPage.jsx      # Hero landing page with multi-college ecosystem picker
            ├── Login.jsx            # Auth entry page
            ├── Discovery.jsx        # Swipe card discovery & live QR Scanner
            ├── Community.jsx        # Campus feed & Community Club Groups tab
            ├── Chat.jsx             # Real-time direct & group chat interface
            ├── Find.jsx             # Student search with Seniority & Department filters
            ├── LocationTracking.jsx # Adaptive campus location map with user clustering
            ├── Requests.jsx         # Connection / Friend request management
            ├── Profile.jsx          # Student profile view & verified ops stats
            ├── EditProfile.jsx      # Profile editor
            ├── ClubHub.jsx          # Campus clubs catalog
            ├── ClubLeadDashboard.jsx# Leader dashboard with QR Check-In Token Generator
            └── Feedback.jsx         # Campus user feedback submission

🧪 Roadmap & Future Vision

  • Campus Gatekeeper Verification
  • Real-Time Admin Kill-Switch
  • Student Profile Management
  • Friend Request Handshake Engine
  • Direct & Ephemeral Group Chat
  • WebGL Light Rays Background Shaders
  • QR-Code Physical Event Check-In System
  • Community Club Groups & Leaderboard
  • Adaptive Location Density Mapping
  • Seniority (Junior / Senior) Filtering
  • ID Card Verification Onboarding
  • 🤖 AI Matchmaker: ML-driven student pairing based on project goals & interests.
  • 📱 Mobile Native: React Native mobile app build for iOS & Android.
  • 🔒 End-to-End Encrypted Chat: Client-side payload encryption for private messages.

🤝 Contributing

Contributions make the campus community thrive! To contribute:

  1. Fork the Repository.
  2. Create a Feature Branch: git checkout -b feature/CoolCampusFeature
  3. Commit your Changes: git commit -m 'Add CoolCampusFeature'
  4. Push to the Branch: git push origin feature/CoolCampusFeature
  5. Open a Pull Request.

📜 License

Distributed under the MIT License. See LICENSE for details.

Built with ❤️ for students, by students. If you find Campus Connect helpful, give it a ⭐ on GitHub!

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages