Aquileo | GitHub - Ahtishamali17/foundit: 🔍 AI-Powered Campus Lost & Found Platform for NIET Noida | NLP Matching | JWT Auth | MongoDB | Node.js

FoundIt is an AI-powered Lost & Found web platform built for college campuses.
Students can report lost/found items, get intelligent AI matches, and connect securely — all in one place.

🔴 Live Demo • 📖 API Docs • 🐛 Report Bug • 💡 Request Feature

📸 Preview

Home Page	Dashboard	Item Detail

✨ Features

🎨 Frontend

⚡ Glassmorphism UI — frosted glass, dark theme
📱 Fully Responsive — mobile + desktop
🔀 Multi-step Post Form — image upload + validation
📊 Live Dashboard — analytics, My Items, Messages
🔍 Smart Search — with fuzzy matching (typo-tolerant)
💬 Real-time Chat — message item owners
🔔 Toast Notifications — instant feedback
🌊 Animated UI — word-by-word hero, shimmer gradients

⚙️ Backend

🔐 JWT Authentication — secure login/register
🖼 Image Upload — Multer (local) or Cloudinary
🤖 AI NLP Matching — TF-IDF + Cosine Similarity
🧠 Image Similarity — MobileNet embeddings (optional)
💡 Smart Recommendations — personalized feed
🔎 Fuzzy Search — Fuse.js typo handling
🗄 MongoDB — indexed for speed, geo-ready
🔌 Socket.io — real-time chat engine

🤖 AI / NLP Engine

This is what makes FoundIt stand out from a basic CRUD app:

New Item Posted
      │
      ▼
┌─────────────────────────────────────────────┐
│           NLP PIPELINE                       │
│                                             │
│  Text → Lowercase → Tokenize               │
│       → Remove Stopwords                   │
│       → Porter Stemmer                     │
│       → TF-IDF Vectors                     │
│       → Cosine Similarity                  │
└──────────────────┬──────────────────────────┘
                   │
      ┌────────────▼────────────┐
      │   COMBINED SCORE        │
      │                         │
      │  Text Sim   × 40%       │
      │  Category   × 25%       │
      │  Date Prox  × 20%       │
      │  Location   × 15%       │
      └────────────┬────────────┘
                   │
      ┌────────────▼────────────┐
      │  IMAGE SIMILARITY       │
      │  (if TF.js installed)   │
      │  MobileNet Embeddings   │
      │  + Cosine Similarity    │
      └────────────┬────────────┘
                   │
                   ▼
         Matches saved in DB
         Both items notified

Component	Technology	Score Weight
Text Similarity	TF-IDF + Cosine	40%
Category Match	Exact Match	25%
Date Proximity	Linear Decay (30d)	20%
Location Overlap	Jaccard Similarity	15%
Image Similarity	MobileNet v2 (optional)	Bonus
Fuzzy Search	Fuse.js (threshold 0.4)	Search only

🏗 Project Structure

foundit/
│
├── 📄 index.html                    ← Complete frontend (single file SPA)
├── 📄 .gitignore
├── 📄 README.md
│
└── 📁 backend/
    ├── 📄 server.js                 ← Main Express server + all routes
    ├── 📄 package.json
    ├── 📄 .env.example
    │
    ├── 📁 utils/                    ← 🆕 AI/NLP Modules
    │   ├── 🤖 nlp.js               ← TF-IDF, cosine, fuzzy, keywords
    │   ├── 🤖 aiMatcher.js         ← Matching engine (runs on item post)
    │   ├── 🤖 recommender.js       ← Personalized recommendation feed
    │   └── 🖼 imageSimilarity.js   ← MobileNet image embeddings
    │
    ├── 📁 config/
    │   └── db.js                   ← MongoDB connection
    │
    ├── 📁 models/
    │   ├── User.model.js
    │   ├── Item.model.js           ← Extended with matches[], keywords[], embeddings[]
    │   └── Chat.model.js
    │
    ├── 📁 controllers/
    │   ├── auth.controller.js
    │   ├── item.controller.js
    │   └── chat.controller.js
    │
    ├── 📁 routes/
    │   ├── auth.routes.js
    │   ├── item.routes.js
    │   ├── chat.routes.js
    │   ├── user.routes.js
    │   └── notification.routes.js
    │
    ├── 📁 middleware/
    │   ├── auth.middleware.js
    │   ├── upload.middleware.js
    │   └── validate.middleware.js
    │
    ├── 📁 services/
    │   ├── aiMatching.service.js
    │   ├── cloudinary.service.js
    │   └── email.service.js
    │
    ├── 📁 sockets/
    │   └── chat.socket.js
    │
    └── 📁 uploads/                  ← Auto-created on first run

🚀 Getting Started

Prerequisites

Make sure you have these installed:

node --version    # v18.0.0 or higher
npm --version     # v9.0.0 or higher

Node.js 18+
MongoDB (local) or MongoDB Atlas (free cloud)
VS Code (recommended)
Git

📦 Installation

Step 1 — Clone the repository

git clone https://github.com/Ahtishamali17/foundit.git
cd foundit

Step 2 — Setup backend

cd backend
npm install

Step 3 — Configure environment

# Windows
copy .env.example .env

# Mac / Linux
cp .env.example .env

Now open .env and fill in your values:

# ── Server ──────────────────────────────
NODE_ENV=development
PORT=5000

# ── MongoDB ─────────────────────────────
# Option A: Local MongoDB (if MongoDB Compass installed)
MONGO_URI=mongodb://localhost:27017/foundit

# Option B: MongoDB Atlas (free cloud)
# MONGO_URI=mongodb+srv://<user>:<pass>@cluster0.xxxxx.mongodb.net/foundit

# ── JWT ─────────────────────────────────
JWT_SECRET=your_super_secret_key_min_32_chars

# ── Admin ───────────────────────────────
ADMIN_EMAIL=admin@foundit.app

# ── Cloudinary (optional - for cloud image storage) ──
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

Step 4 — Start the server

npm run dev

You should see:

╔══════════════════════════════════════════╗
║   FoundIt AI — NIET Noida Campus          ║
╠══════════════════════════════════════════╣
║  🌐 App    : http://localhost:5000         ║
║  ⚙️  API    : http://localhost:5000/api    ║
║  🤖 NLP    : TF-IDF + Cosine + Fuzzy      ║
║  🏥 Health : http://localhost:5000/api/health║
╚══════════════════════════════════════════╝

✅ MongoDB connected!

Step 5 — Open in browser

http://localhost:5000

The frontend (index.html) is served automatically by the backend — no separate server needed!

⚡ Optional: Enable Image AI

For MobileNet-powered image similarity (optional, adds ~500MB):

npm install @tensorflow/tfjs-node @tensorflow-models/mobilenet jimp

The system gracefully works without it — image similarity is simply skipped.

📡 API Documentation

Base URL

http://localhost:5000/api

🔐 Authentication

Method	Endpoint	Auth	Description
`POST`	`/auth/register`	❌	Create new account
`POST`	`/auth/login`	❌	Login, get JWT token
`GET`	`/auth/me`	✅	Get current user

Register:

POST /api/auth/register
{
  "name": "Ahtisham Ali",
  "email": "ahtisham@niet.co.in",
  "password": "password123",
  "college": "NIET Noida",
  "phone": "+91 9876543210"
}

Login Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "_id": "...", "name": "Ahtisham Ali", "email": "ahtisham@niet.co.in" }
}

📦 Items

Method	Endpoint	Auth	Description
`GET`	`/items`	❌	Get all items (filter, paginate)
`GET`	`/items/mine`	✅	Get my items (dashboard)
`GET`	`/items/search?q=`	❌	🆕 NLP fuzzy search
`GET`	`/items/:id`	❌	Get single item
`GET`	`/items/:id/matches`	❌	🆕 AI matches for item
`POST`	`/items`	✅	Post new item (multipart/form-data)
`PUT`	`/items/:id`	✅	Update item
`PUT`	`/items/:id/resolve`	✅	Mark as resolved
`DELETE`	`/items/:id`	✅	Delete item

Query Parameters for GET /api/items:

Param	Type	Example
`type`	string	`lost` or `found`
`category`	string	`Electronics`
`status`	string	`pending` or `resolved`
`search`	string	`headphones`
`fuzzy`	boolean	`true`
`page`	number	`1`
`limit`	number	`12`

Create Item (multipart/form-data):

POST /api/items
Authorization: Bearer <token>

Fields:
  title          (required)
  description    (required)
  type           lost | found (required)
  category       (required)
  location       (required)
  date           YYYY-MM-DD (required)
  image          file (optional)
  contactName
  contactEmail
  contactPhone

GET /api/items/:id/matches response:

{
  "success": true,
  "data": [
    {
      "_id": "...",
      "title": "Black Sony Headphones",
      "type": "found",
      "_matchScore": 0.82,
      "_matchImgScore": 74,
      "_matchBreakdown": {
        "text": 78,
        "category": 100,
        "date": 80,
        "location": 60,
        "final": 82
      },
      "_matchReason": "same category, similar description, close date"
    }
  ]
}

🤖 AI & Recommendations

Method	Endpoint	Auth	Description
`GET`	`/recommendations`	✅	🆕 Personalized item feed
`POST`	`/admin/rerun-matching`	✅ Admin	🆕 Re-run AI on all items

GET /api/recommendations response:

{
  "success": true,
  "data": [ ...items with _recScore and _recReason ],
  "meta": {
    "total": 8,
    "interestKeywords": ["headphones", "sony", "charger", "electronics"],
    "basedOn": "your activity"
  }
}

📊 Stats

Method	Endpoint	Auth	Description
`GET`	`/stats`	❌	Platform-wide counts
`GET`	`/health`	❌	Server + DB health

🗄 Database Schema

User

{
  name:      String,   // required
  email:     String,   // unique, lowercase
  password:  String,   // bcrypt hashed, never returned
  college:   String,   // default: "NIET Noida"
  phone:     String,
  createdAt: Date,
  updatedAt: Date
}

Item (AI-enhanced)

{
  // Core fields
  title:       String,   // required
  description: String,   // required
  type:        "lost" | "found",
  category:    String,
  status:      "pending" | "resolved",
  image:       String,   // filename
  location:    String,
  date:        Date,
  contact:     { name, email, phone },
  userId:      ObjectId,
  userName:    String,
  views:       Number,

  // 🆕 AI fields
  matches: [{
    itemId:    ObjectId,
    score:     Number,    // 0–1 combined score
    imgScore:  Number,    // 0–100 image similarity %
    breakdown: { text, category, date, location, final },
    reason:    String     // human-readable explanation
  }],
  imageEmbedding: [Number],  // 1024-dim MobileNet vector (hidden from API)
  keywords:       [String]   // auto-extracted NLP keywords
}

🛠 Tech Stack

Layer	Technology
Frontend	HTML5, CSS3, Vanilla JS (Glassmorphism SPA)
Backend	Node.js, Express.js
Database	MongoDB, Mongoose
Auth	JWT (JSON Web Tokens), bcryptjs
AI/NLP	natural (TF-IDF), Fuse.js (fuzzy), custom cosine similarity
Image AI	TensorFlow.js + MobileNet v2 (optional)
File Upload	Multer (local) / Cloudinary (cloud)
Real-time	Socket.io
Dev Tools	Nodemon, dotenv

🌐 Deployment Guide

Frontend → GitHub Pages / Netlify

# Netlify drag-and-drop: just upload index.html
# Or via CLI:
npm install -g netlify-cli
netlify deploy --prod --dir=. --site=YOUR_SITE_ID

Backend → Render (Free)

Push your code to GitHub
Go to render.com → New Web Service
Connect your GitHub repo → select backend/ as root
Build: npm install
Start: npm start
Add Environment Variables from your .env

Database → MongoDB Atlas (Free)

Create account at mongodb.com/atlas
Create a free M0 cluster
Database Access → Add user with password
Network Access → Allow 0.0.0.0/0
Connect → Drivers → Copy connection string
Replace <password> and add /foundit at end

🧪 Test the AI

After starting the server, try these:

# 1. Register
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Ahtisham Ali","email":"test@niet.co.in","password":"test1234"}'

# 2. Post a LOST item
curl -X POST http://localhost:5000/api/items \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Sony WH-1000XM5 Headphones","description":"Black noise-cancelling Sony headphones with white case","type":"lost","category":"Electronics","location":"NIET Main Library","date":"2024-12-28"}'

# 3. Post a FOUND item (AI matching fires automatically)
curl -X POST http://localhost:5000/api/items \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Found black Sony headphones","description":"Sony noise cancelling headphones found near library","type":"found","category":"Electronics","location":"NIET Library 2nd floor","date":"2024-12-28"}'

# 4. Check AI matches (wait 1-2 seconds for async matching)
curl http://localhost:5000/api/items/ITEM_ID/matches

# 5. Fuzzy search (typo test!)
curl "http://localhost:5000/api/items/search?q=headfones"
curl "http://localhost:5000/api/items/search?q=soni+headphone"

🔒 Security Features

✅ JWT — stateless auth with 7-day expiry
✅ bcrypt — 12 salt rounds password hashing
✅ CORS — configurable origin whitelist
✅ Input validation — all POST/PUT routes
✅ File type check — Multer rejects non-images
✅ Password hidden — select: false on schema
✅ Error handling — global Express error handler
✅ No sensitive data in responses — clean JSON

📈 Roadmap

🤝 Contributing

Contributions are welcome! Here's how:

# 1. Fork the repo on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/foundit.git

# 3. Create feature branch
git checkout -b feature/amazing-feature

# 4. Make changes & commit
git add .
git commit -m "feat: add amazing feature"

# 5. Push & open PR
git push origin feature/amazing-feature

Please follow conventional commits format.

📄 License

Distributed under the MIT License. See LICENSE for more information.

👨‍💻 Author

Ahtisham Ali

Full Stack Developer | NIET Noida

⭐ Support

If this project helped you or you think it's cool — please give it a star! ⭐

It helps others discover the project and motivates continued development.

Built with ❤️ for NIET Noida Campus — by Ahtisham Ali

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
backend		backend
uploads		uploads
.gitignore		.gitignore
AI-powered logo for lost & found.ico		AI-powered logo for lost & found.ico
AI-powered logo for lost & found.png		AI-powered logo for lost & found.png
LICENSE		LICENSE
README.md		README.md
gitignore		gitignore
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation