🌐 IIIT Social

The Campus Operating System – Syncing grades, social life, and everything in between.

IIIT Social is a comprehensive campus-wide platform designed to unify fragmented communication channels, streamline student interactions, and foster meaningful connections across the IIIT Hyderabad community.

---

📖 Table of Contents

• The Problem
• Our Solution
• Key Features
• Tech Stack
• Getting Started
• Project Structure
• API Documentation
• Contributing
• AI Development Disclosure
• License

---

🔍 The Problem

Campus life at IIIT Hyderabad faces several disconnected challenges:

🗨️ The Disconnected Campus

Students juggle 4+ messaging apps (WhatsApp, Discord, Telegram, Instagram) for different groups, leading to:

• Missed announcements buried in group spam
• Zero discoverability of events, clubs, or opportunities
• No way to connect with like-minded peers outside your immediate circle

📱 The Messy Communication Maze

• Many WhatsApp groups with overlapping purposes
• Important updates lost in meme floods
• No searchable history or organized threads
• Anonymous questions asked publicly on Facebook with delayed responses

🎲 The Teammate Roulette

Course projects and hackathons turn into a scramble:

• "Looking for a backend dev for HCI project" posts get lost in group chats
• Shallow matching based on social connections rather than skills
• Last-minute team formation leads to misaligned expectations

🚶 The Solo Barrier

• Students want to attend events but hesitate to go alone
• No visibility into who else is attending workshops, concerts, or talks
• Potential friendships never form due to lack of discovery mechanisms

🔒 The Trust Issue

Sensitive topics (mental health, academic struggles, career confusion) lack safe, judgment-free spaces for discussion.

---

💡 Our Solution

IIIT Social consolidates all campus interactions into a single, intuitive platform—a true "campus operating system" that combines:

🎯 Four Core Pillars

1️⃣ Campus Forum (Anonymous & Threaded)

• Anonymous Posting: Discuss sensitive topics (mental health, career doubts, complaints) without revealing identity
• Threaded Discussions: Reddit-style nested comments for organized conversations
• Topic Tags: Filter by academics, events, social, complaints, confessions
• Search & Archive: Find old discussions and relevant advice instantly
• Upvote/Downvote System: Community-moderated content quality

2️⃣ Live "Friend Radar" (Real-time Location)

• Interactive Campus Map: Leaflet-based visualization of IIIT campus
• Real-time Friend Locations: See which friends are at the library, mess, or sports complex
• Privacy Controls: Toggle location sharing on/off with granular permissions
• Location-based Discovery: Find students near specific buildings or events
• Visual Heatmaps: See popular campus spots at different times

3️⃣ Unified Marketplace

A one-stop hub for campus transactions and gig work:

• Cab Sharing: Find ride companions for airport/city trips with cost splitting
• Buy/Sell: Textbooks, electronics, furniture, sports equipment with category filters
• Lost & Found: Report and search for lost items with image upload
• Campus Gigs: Post tasks (food runs, study help, surveys, skill trades) with rewards
• Mess Bookings: Trade meal slots or find dinner companions
• Applicant Management: Accept/reject applicants for gigs with status tracking

4️⃣ Direct Connect (Private Messaging)

• 1-on-1 Conversations: Secure messaging between students
• Emoji Reactions: Express reactions to messages
• Read Receipts: See message delivery and read status
• Rich Media: Share images, files, and links
• Conversation History: Searchable message archives

---

✨ Key Features

🎨 Arc Browser-Inspired Design

• Sleek Sidebar Navigation: Persistent left sidebar with icon-based menu
• Cyber-themed UI: Dark mode with neon accents, glassmorphism effects
• Smooth Animations: Framer Motion-powered transitions and micro-interactions
• Responsive Layout: Mobile-first design that adapts to all screen sizes

💳 Tinder-Like Browsing Interface

• Team Matching Carousel: Swipe through potential teammates with 3D flip cards
• Interactive Questionnaires: Context-aware questions for courses/events
• Smart Matching Algorithm: Pair students based on skills, availability, and preferences
• Visual Match Results: Celebratory animations for successful matches

🔐 Dual Identity System

• Public Profile: Full name, avatar, resume, skills for professional networking
• Anonymous Profile: Auto-generated avatar and nickname for sensitive discussions
• Context Switching: Seamlessly toggle between identities based on post type

📊 Real-time Updates

• Live Notifications: Instant alerts for messages, matches, and marketplace activity
• Socket.io Integration: Real-time messaging and location updates
• Background Sync: Automatic data refresh without manual reloading

🛡️ Privacy & Security

• JWT Authentication: Secure token-based auth with refresh tokens
• Environment Protection: .env files excluded from version control
• CORS Configuration: Controlled cross-origin requests
• Input Validation: Server-side validation for all API requests

---

🛠️ Tech Stack

Frontend

Technology	Version	Purpose
React	19.2.0	Component-based UI framework
TypeScript	5.9.3	Type-safe JavaScript
Vite	7.2.4	Lightning-fast build tool with HMR
TailwindCSS	4.1.18	Utility-first CSS framework
React Router	7.13.0	Client-side routing
React Query	5.90.20	Server state management & caching
Zustand	5.0.10	Lightweight state management
Leaflet	1.9.4	Interactive maps for location features
Framer Motion	12.29.0	Animation library
Lucide React	0.563.0	Icon library
Axios	1.13.2	HTTP client
React Hook Form	7.71.1	Form validation
date-fns	4.1.0	Date manipulation
Emoji Mart	5.6.0	Emoji picker

Backend

Technology	Version	Purpose
Node.js	20+	JavaScript runtime
Express.js	4.18.2	Web application framework
MongoDB	6.3.0	NoSQL database
Mongoose	8.0.0	MongoDB ODM with schema validation
JWT	9.0.2	Token-based authentication
bcryptjs	2.4.3	Password hashing
Socket.io	4.6.0	Real-time bidirectional communication
Express Validator	7.0.1	Request validation middleware
Multer	1.4.5-lts.1	File upload handling
CORS	2.8.5	Cross-origin resource sharing
dotenv	16.3.1	Environment variable management

Architecture

• Frontend: Component-based architecture with React hooks and custom hooks
• Backend: MVC pattern with RESTful API design
• Database: MongoDB with Mongoose schemas and indexes
• Authentication: JWT with access/refresh token rotation
• Real-time: Socket.io for live messaging and location updates
• State Management: React Query for server state, Zustand for client state

---

🚀 Getting Started

Prerequisites

• Node.js: v18.0.0 or higher (Download)
• MongoDB: v6.0 or higher (Download)
• Git: Latest version (Download)
• npm: Comes with Node.js (or use yarn/pnpm)

Installation

1️⃣ Clone the Repository

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

2️⃣ Backend Setup

# Navigate to backend directory
cd Backend

# Install dependencies
npm install

# Create environment file
cp .env.example .env

Configure .env file:

# Database
MONGODB_URI=

# Server
PORT=3000
NODE_ENV=development

# JWT Authentication
JWT_SECRET=your_super_secret_jwt_key_change_this_in_production
JWT_EXPIRES_IN=7d

# Frontend URL (for CORS)
FRONTEND_URL=http://localhost:5173

Start the backend server:

# Development mode with auto-restart
npm run dev

# OR Production mode
npm start

Backend will run on http://localhost:3000

3️⃣ Frontend Setup

# Navigate to frontend directory (from project root)
cd Frontend

# Install dependencies
npm install

# Create environment file (optional)
echo "VITE_API_URL=http://localhost:3000" > .env.local

Start the frontend development server:

npm run dev

Frontend will run on http://localhost:5173

4️⃣ Seed Sample Data (Optional)

# From Backend directory
cd Backend

# Seed marketplace and gigs data
npm run seed:marketplace

# OR seed all data (users, profiles, events, etc.)
npm run seed

This will create:

• 10 sample gigs (food runs, study help, surveys, skill trades)
• 15 marketplace items (mess bookings, books, electronics, furniture, sports)
• Sample user accounts and profiles

---

📁 Project Structure

IIIT-Social/
├── Backend/                      # Express.js backend server
│   ├── src/
│   │   ├── models/               # Mongoose schemas
│   │   │   ├── User.js
│   │   │   ├── Profile.js
│   │   │   ├── Marketplace.js
│   │   │   ├── Gigs.js
│   │   │   ├── Event.js
│   │   │   ├── Anonymous.js
│   │   │   ├── Matching.js
│   │   │   ├── Messaging.js
│   │   │   └── Notification.js
│   │   ├── routes/               # API route handlers
│   │   │   ├── auth.js
│   │   │   ├── profile.js
│   │   │   ├── marketplace.js
│   │   │   ├── events.js
│   │   │   ├── matching.js
│   │   │   ├── messages.js
│   │   │   └── notifications.js
│   │   ├── middleware/           # Express middleware
│   │   │   ├── auth.js
│   │   │   └── validation.js
│   │   ├── controllers/          # Business logic
│   │   ├── scripts/              # Database seeding scripts
│   │   │   ├── seed.js
│   │   │   └── seed-marketplace.js
│   │   └── server.js             # Express app entry point
│   ├── .env                      # Environment variables (gitignored)
│   ├── .env.example              # Environment template
│   └── package.json
│
├── Frontend/                     # React + TypeScript frontend
│   ├── src/
│   │   ├── components/           # Reusable UI components
│   │   │   ├── layout/
│   │   │   │   ├── Sidebar.tsx
│   │   │   │   └── Layout.tsx
│   │   │   ├── common/
│   │   │   │   ├── Button.tsx
│   │   │   │   ├── Modal.tsx
│   │   │   │   └── Card.tsx
│   │   │   └── features/
│   │   ├── pages/                # Route components
│   │   │   ├── HomePage.tsx
│   │   │   ├── ForumPage.tsx
│   │   │   ├── MarketplacePage.tsx
│   │   │   ├── TeamMatchPage.tsx
│   │   │   ├── EventsPage.tsx
│   │   │   ├── LocationPage.tsx
│   │   │   └── MessagesPage.tsx
│   │   ├── hooks/                # Custom React hooks
│   │   ├── store/                # Zustand stores
│   │   ├── utils/                # Helper functions
│   │   ├── types/                # TypeScript type definitions
│   │   ├── App.tsx               # Root component
│   │   └── main.tsx              # Entry point
│   ├── public/                   # Static assets
│   ├── index.html
│   ├── tailwind.config.js        # TailwindCSS configuration
│   ├── vite.config.ts            # Vite configuration
│   └── package.json
│
├── Documents/                    # Project documentation
│   └── api-documentation.md      # Comprehensive API docs
│
└── README.md                     # This file

---

📚 API Documentation

Comprehensive API documentation is available in Documents/api-documentation.md.

Quick Reference

Base URL: http://localhost:3000/api

Authentication

• POST /auth/register - Register new user
• POST /auth/login - User login
• POST /auth/refresh - Refresh access token
• GET /auth/me - Get current user

Marketplace

• GET /marketplace - List all marketplace items (with filters)
• POST /marketplace - Create new item
• PUT /marketplace/:id - Update item
• DELETE /marketplace/:id - Delete item
• POST /marketplace/:id/apply - Apply to marketplace item
• POST /marketplace/:id/accept/:applicantId - Accept applicant
• POST /marketplace/:id/reject/:applicantId - Reject applicant

Gigs

• GET /gigs - List all gigs (with filters)
• POST /gigs - Create new gig
• PUT /gigs/:id - Update gig
• DELETE /gigs/:id - Delete gig
• POST /gigs/:id/apply - Apply to gig

Team Matching

• POST /matching/create - Create new team match request
• GET /matching/matches - Get potential matches
• POST /matching/respond - Respond to match (accept/reject)

Events

• GET /events - List all events
• POST /events - Create new event
• POST /events/:id/rsvp - RSVP to event

Messaging

• GET /messages/conversations - List all conversations
• GET /messages/:conversationId - Get conversation messages
• POST /messages/:conversationId - Send message

---

🤝 Contributing

We welcome contributions from the IIIT community! Here's how you can help:

Development Workflow

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes
   • Follow existing code style and conventions
   • Write clear commit messages
   • Add comments for complex logic
4. Test your changes
   • Run frontend: cd Frontend && npm run dev
   • Run backend: cd Backend && npm run dev
   • Test all affected features
5. Commit and push

   git add .
   git commit -m "feat: add your feature description"
   git push origin feature/your-feature-name

6. Create a Pull Request
   • Provide a clear description of changes
   • Reference any related issues
   • Wait for code review

Code Style Guidelines

• Frontend: Use TypeScript, follow React hooks best practices
• Backend: Use ES6+ features, async/await for async operations
• Formatting: Prettier/ESLint configured (run npm run lint)
• Commits: Use conventional commits (feat, fix, docs, refactor, etc.)

Areas to Contribute

• 🐛 Bug fixes and issue resolution
• ✨ New features (marketplace categories, event types, etc.)
• 📖 Documentation improvements
• 🎨 UI/UX enhancements
• ⚡ Performance optimizations
• 🧪 Test coverage expansion

---

🤖 AI Development Disclosure

This project was developed with significant assistance from AI tools (primarily Claude 3.5 Sonnet and GitHub Copilot) to accelerate development and enhance code quality.

AI Contribution Areas

1. Code Generation: Initial component scaffolding, boilerplate reduction, and repetitive pattern implementation
2. Debugging: Identifying syntax errors, logic issues, and edge cases
3. Architecture Decisions: Suggesting best practices for React patterns, MongoDB schema design, and API structure
4. Documentation: Generating comprehensive README, inline code comments, and API documentation
5. Responsive Design: Implementing TailwindCSS breakpoints and layout strategies
6. Problem Solving: Resolving git merge conflicts, dependency issues, and configuration errors

Human Oversight

While AI tools provided substantial assistance, all core decisions were made by human developers:

• Product Vision: Problem definition, feature prioritization, and user experience design
• Business Logic: Team matching algorithms, marketplace rules, and privacy controls
• Code Review: Manual verification of AI-generated code for correctness and security
• Testing: Comprehensive manual testing of all features and user flows
• Integration: Connecting frontend/backend, database design, and third-party services

Learning Outcomes

Using AI as a development partner enabled:

• Faster Prototyping: Reduced development time from months to weeks
• Higher Quality: Leveraged AI knowledge of best practices and common pitfalls
• Skill Development: Learned new patterns and techniques through AI explanations
• Focus on Innovation: Spent more time on unique features rather than boilerplate

We believe in transparency about AI usage and view it as a powerful tool for learning and productivity—not a replacement for human creativity and judgment.

---

📄 License

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

---

👥 Team

Developed with ❤️ by students of IIIT Hyderabad for the campus community.

Contact: [Your Email] | [GitHub Profile]

---

🙏 Acknowledgments

• IIIT Hyderabad for providing the inspiration and environment
• Open Source Community for amazing libraries and tools
• AI Assistants (Claude, GitHub Copilot) for development support
• Early Testers for valuable feedback and feature suggestions

---

🔮 Future Roadmap

• Mobile App: React Native version for iOS/Android
• Push Notifications: Browser notifications for real-time alerts
• Advanced Search: Full-text search across forum, marketplace, and events
• Analytics Dashboard: Personal activity insights and campus trends
• Course Integration: Link to IIIT course catalog and registration
• Club Management: Dedicated pages for student clubs and societies
• Gamification: Badges, points, and leaderboards for engagement
• AI Recommendations: Personalized event suggestions and teammate matching
• Video Calls: Integrated video chat for group project coordination

---

Built for IIIT, by IIIT students 🚀

Report Bug · Request Feature · Contribute

- Direct Messaging - Notifications

Tech Stack

Backend: Express, MongoDB, Mongoose, JWT, Socket.IO
Frontend: React, TypeScript, Vite, TanStack Query, Tailwind

API Endpoints

All endpoints require Authorization: Bearer <token> except signup/login.

• POST /api/auth/signup - Register
• POST /api/auth/login - Login
• GET /api/profile/me - Get profile
• GET /api/marketplace - List items
• GET /api/events - List events
• GET /api/groups - List groups
• GET /api/matching/matches - Get matches
• GET /api/messages/channels - Get channels
• GET /api/notifications - Get notifications