FindIt — Smart Lost & Found Platform

FindIt is a smart digital assistant for lost belongings. If you lose something, you post it; if you find something, you post it. The platform automatically matches reports, lets you chat anonymously, and uses a secure 6-digit code (OTP) during the handoff.

---

Features

• Smart Matching: Automatically compares lost and found reports based on category, location, and description to find the most relevant matches instantly.
• Location Pinning: Drop precise pins on an interactive map for location-based matching and item tracking.
• Real-Time Messaging: Communicate instantly and anonymously with potential matches through built-in Socket.io messaging.
• Secure Handoff System: Verify the return of items using a unique 6-digit OTP generated by the owner and verified by the finder.
• Community Trust Scores: A dynamic reputation system where users earn trust points (+10) for every successful, OTP-verified item return. This ensures the community remains safe and reliable by highlighting honest and active participants.
• Instant Notifications: Stay updated with automated alerts via SMS (Twilio) or Email (Nodemailer) the moment a match is detected.

---

How It Works

1. Report: Submit details, upload photos, and pin the location of your lost or found item.
2. AI Match: The platform analyzes all active reports and presents the most accurate matches in real-time.
3. Connect: Use the secure, anonymous chat interface to coordinate details and a safe meetup location.
4. Handoff: Meet in person and verify the exchange using a secure, owner-generated OTP token.
5. Trust Build: Upon successful verification, both users receive trust score points (+10), strengthening their community standing and platform credibility.

---

Tech Stack

• Frontend: React, Vite, Tailwind CSS, Leaflet Maps, Socket.io Client, Google OAuth, React Router
• Backend: Node.js, Express, Socket.io, Nodemailer, Twilio SDK
• Database: PostgreSQL (pg)

---

Folder Structure

smart-lost-found/
├── client/                 
│   ├── src/
│   │   ├── components/     
│   │   ├── pages/          
│   │   ├── contexts/      
│   │   ├── assets/        
│   │   └── main.jsx       
│   └── tailwind.config.js  
├── server/                 
│   ├── config/             
│   ├── controllers/        
│   ├── models/             
│   ├── routes/             
│   ├── services/           
│   ├── middleware/         
│   └── index.js
└── README.md               

---

Getting Started

1. Clone the repository

git clone <repo-url>
cd smart-lost-found

2. Setup Environment Variables

Create a .env file in both the client and server directories based on the guides below:

Backend (server/.env)

Variable	Description
DATABASE_URL	PostgreSQL connection string (e.g., postgresql://user:pass@localhost:5432/db)
PORT	Port number for the backend server (default: 2017)
JWT_SECRET	Secret key for signing JSON Web Tokens
EMAIL_USER	Gmail address used for sending automated emails
EMAIL_PASS	Google App Password (not your regular password)
FRONTEND_URL	URL where the frontend is hosted (for CORS)
BACKEND_URL	URL where the backend is hosted
GOOGLE_CLIENT_ID	Client ID from Google Cloud Console for OAuth
TWILIO_ACCOUNT_SID	Your Twilio Account SID for SMS alerts
TWILIO_AUTH_TOKEN	Your Twilio Auth Token
TWILIO_PHONE_NUMBER	Your Twilio virtual phone number
GEMINI_API_KEY	API Key for Google Gemini (AI matching logic)

Frontend (client/.env)

Variable	Description
VITE_API_URL	The full URL of your running backend API
VITE_GOOGLE_CLIENT_ID	Client ID for Google Login integration

---

Database Initialization

FindIt uses a PostgreSQL database. The application is designed to be plug-and-play regarding the database schema.

Automatic Table Creation: When you start the server (npm start), it automatically checks for and creates the following essential tables:

• users: User profiles, credentials, and Trust Scores.
• reports: Details of lost and found items including coordinates.
• matches: Mapping of potential item matches.
• messages: Real-time chat history between users.
• handoffs: Secure 6-digit OTP verification data.
• notifications & contacts: System alerts and support queries.

3. Install Dependencies

cd client && npm install
cd ../server && npm install

4. Run the Platform

In two terminals:

# Terminal 1 (Frontend)
cd client
npm run dev

# Terminal 2 (Backend)
cd server
npm start

---

Usage

• Go to http://localhost:5173 (or the port shown in terminal)
• Register or log in
• Report a lost or found item
• Browse matches and chat securely
• Meet and verify handoff with OTP

---

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

---

📸 Screenshots

---