Skip to content

Commit f9def7b

Browse files
pratham-developerpratham-developer
committed
editreadme.md
1 parent a4e177b commit f9def7b

File tree

1 file changed

+195
-27
lines changed

1 file changed

+195
-27
lines changed

โ€ŽREADME.mdโ€Ž

Lines changed: 195 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,195 @@
1-
# FindIT Backend
2-
3-
This is the backend API for FindIT, a lost and found platform for VIT students. It provides RESTful endpoints for user authentication, posting and searching lost/found items, and secure item claiming using QR codes.
4-
5-
## Features
6-
- User authentication via Google (Firebase)
7-
- Post, search, and filter lost/found items
8-
- Image upload support (Cloudinary)
9-
- Secure item claiming with QR codes
10-
11-
## Tech Stack
12-
- Node.js, Express.js
13-
- MongoDB (Mongoose)
14-
- Firebase (Google Auth)
15-
- Cloudinary (image storage)
16-
17-
## API Endpoints (Summary)
18-
- `POST /user/login` โ€” Login/register user
19-
- `GET /user` โ€” Get user details
20-
- `POST /item` โ€” Post a new item (with image)
21-
- `GET /item` โ€” List/search items
22-
- `GET /item/:id` โ€” Get item by ID
23-
- `GET /item/user/posts` โ€” Get user's posted items
24-
- `GET /item/user/claims` โ€” Get user's claimed items
25-
- `POST /claim/generate-qr/:itemId` โ€” Generate QR for item
26-
- `POST /claim/claim-item` โ€” Claim item via QR
27-
- `GET /claim/status/:itemId` โ€” Check claim status
1+
# <img src="https://img.icons8.com/color/48/000000/search--v1.png" width="36" style="vertical-align:middle;"/> FindIt โ€“ Lost & Found App for VIT
2+
3+
<p align="center">
4+
<img src="https://img.shields.io/badge/Institute-VIT%20Vellore-blueviolet" alt="Institute"/>
5+
<img src="https://img.shields.io/badge/Backend-Node.js-green" alt="Node.js"/>
6+
<img src="https://img.shields.io/badge/Android%20Client-Kotlin-pink" alt="Kotlin"/>
7+
<img src="https://img.shields.io/badge/Database-MongoDB-brightgreen" alt="MongoDB"/>
8+
<img src="https://img.shields.io/badge/Auth-Firebase-orange" alt="Firebase"/>
9+
<img src="https://img.shields.io/badge/Images-Cloudinary-blue" alt="Cloudinary"/>
10+
<img src="https://img.shields.io/badge/Moderation-TensorFlow.js-yellow" alt="TensorFlow.js"/>
11+
12+
</p>
13+
14+
15+
## ๐Ÿš€ Overview
16+
17+
**FindIt** is a comprehensive campus-wide lost & found platform for VIT students. It enables users to securely report, search, and claim lost items, with robust authentication, image moderation, and QR-based claim verification.
18+
19+
---
20+
21+
## โœจ Features
22+
23+
- **Google-based Authentication (VIT Email Only):**
24+
- Only VIT students can access the platform, ensuring a secure and exclusive environment.
25+
- Seamless login and registration via Firebase.
26+
27+
- **Post, Search, and Filter Lost/Found Items:**
28+
- Users can post lost or found items with detailed descriptions, categories, and images.
29+
- Advanced search and filter options by category, status, and keywords.
30+
- Pagination support for efficient browsing.
31+
32+
- **Image Upload & Moderation:**
33+
- Images are uploaded to Cloudinary for scalable and reliable storage.
34+
- Every image is automatically checked for inappropriate content using TensorFlow.js and NSFWJS.
35+
- Unsafe images are blocked, ensuring a safe community experience.
36+
37+
- **QR Code-Based Item Claiming:**
38+
- Item owners can generate a secure, time-limited QR code for each item.
39+
- Claimers scan the QR code to initiate a secure, verifiable handover.
40+
- JWT-secured tokens ensure authenticity and prevent misuse.
41+
42+
- **User-Specific Item Management:**
43+
- View all items posted or claimed by the logged-in user.
44+
- Delete items (if owner and not claimed) or as an admin.
45+
46+
- **Robust Security:**
47+
- API key validation, rate limiting, and admin-only access for sensitive operations.
48+
- All endpoints protected by authentication middleware.
49+
50+
- **Admin Controls:**
51+
- Special endpoints for moderation, including item deletion and version management.
52+
53+
---
54+
55+
## ๐Ÿ› ๏ธ Tech Stack
56+
57+
- **Backend:** Node.js, Express.js
58+
- **Database:** MongoDB (Mongoose)
59+
- **Authentication:** Firebase (Google Auth)
60+
- **Image Storage:** Cloudinary
61+
- **Image Moderation:** TensorFlow.js, NSFWJS
62+
- **Android Client:** Kotlin
63+
64+
---
65+
66+
## ๐Ÿงฉ Architecture Highlights
67+
68+
- **Image Moderation Pipeline:**
69+
- Node.js worker threads run TensorFlow.js & NSFWJS to analyze uploads for inappropriate content.
70+
- Custom logic blocks unsafe images, ensuring platform safety.
71+
- High concurrency via distributed moderation tasks.
72+
73+
- **QR Code Claiming:**
74+
- JWT-secured, time-limited tokens for secure, verifiable handovers.
75+
- QR codes generated by item owners, scanned by claimers.
76+
77+
- **Security:**
78+
- API key validation, rate limiting, admin-only access for sensitive operations.
79+
80+
---
81+
82+
## ๐Ÿ“š API Endpoints
83+
84+
> **Note:** All endpoints require the `x-api-key` header in addition to authentication (if applicable).
85+
86+
### User Routes (`/user`)
87+
| Method | Path | Description | Auth |
88+
|--------|---------------------|------------------------------------|--------------|
89+
| POST | `/login` | Login/register user (Google Auth) | Firebase |
90+
| GET | `/` | Get user details | Firebase |
91+
| GET | `/admin/test` | Test admin-only access | Admin+Firebase|
92+
93+
### Item Routes (`/item`)
94+
| Method | Path | Description | Auth |
95+
|--------|-------------------------|---------------------------------------------|--------------|
96+
| POST | `/` | Post a new item (with image, NSFW check) | Firebase |
97+
| GET | `/` | List/search items (pagination, filters) | Firebase |
98+
| GET | `/:id` | Get item by ID | Firebase |
99+
| DELETE | `/:itemId` | Delete item (if owner, not claimed) | Firebase |
100+
| GET | `/user/posts` | Get user's posted items | Firebase |
101+
| GET | `/user/claims` | Get user's claimed items | Firebase |
102+
| DELETE | `/admin/:itemId` | Admin: Delete any item | Admin+Firebase|
103+
104+
### Claim Routes (`/claim`)
105+
| Method | Path | Description | Auth |
106+
|--------|-----------------------------|---------------------------------------------|--------------|
107+
| POST | `/generate-qr/:itemId` | Generate QR for item (owner only) | Firebase |
108+
| POST | `/claim-item` | Claim item via QR (claimer) | Firebase |
109+
| GET | `/status/:itemId` | Check claim status of item | Firebase |
110+
111+
### Version Routes (`/version`)
112+
| Method | Path | Description | Auth |
113+
|--------|---------------------|------------------------------------|--------------|
114+
| GET | `/version` | Get current backend version | Public |
115+
| POST | `/admin/version` | Update backend version (admin) | Admin+Firebase|
116+
117+
---
118+
119+
## ๐Ÿ“ Example Usage
120+
121+
### 1. Post a Lost/Found Item
122+
```http
123+
POST /item
124+
Headers:
125+
Authorization: Bearer <Firebase Token>
126+
x-api-key: <your-api-key>
127+
Body: { title, description, contact, category, location, dateFound, image }
128+
```
129+
130+
### 2. Claim an Item via QR
131+
- Owner generates QR: `POST /claim/generate-qr/:itemId` (with `x-api-key` header)
132+
- Claimer scans QR, submits: `POST /claim/claim-item` with token (with `x-api-key` header)
133+
134+
---
135+
136+
## ๐Ÿ›ก๏ธ Security & API Key
137+
138+
- **API Key Required:** All endpoints require a valid API key to be sent in the `x-api-key` header. Requests without a valid key will be rejected with a 403 error.
139+
- **Google Auth:** Only VIT emails allowed
140+
- **Image Moderation:** All uploads checked for NSFW content
141+
- **Rate Limiting:** Prevents abuse on sensitive/admin endpoints
142+
- **Admin Controls:** Special endpoints for moderation
143+
144+
> **How to use:**
145+
> - Obtain your API key from the project admin.
146+
> - Add it to every request header: `x-api-key: <your-api-key>`
147+
148+
---
149+
150+
## โš™๏ธ Setup & Installation
151+
152+
1. **Clone the repository:**
153+
```bash
154+
git clone https://github.com/your-repo/finditBackend.git
155+
cd finditBackend
156+
```
157+
2. **Install dependencies:**
158+
```bash
159+
npm install
160+
```
161+
3. **Configure environment variables:**
162+
- Set up Firebase, MongoDB, and Cloudinary credentials in a `.env` file.
163+
4. **Run the server:**
164+
```bash
165+
npm start
166+
```
167+
168+
---
169+
170+
## ๐Ÿ‘จโ€๐Ÿ’ป Contributing
171+
172+
1. Fork the repo
173+
2. Clone and install dependencies
174+
3. Set up `.env` for Firebase, MongoDB, Cloudinary
175+
4. Run with `npm start`
176+
177+
---
178+
179+
## ๐Ÿซ About
180+
181+
Developed for VIT students to make campus life safer and more convenient.
182+
183+
---
184+
185+
## ๐Ÿ‘จโ€๐Ÿ’ป ๐—ง๐—ฒ๐—ฎ๐—บ
186+
187+
- [Pratham Khanduja](https://github.com/pratham-developer) โ€“ Backend & Android
188+
- [Rudra Gupta](https://github.com/Rudragupta8777) โ€“ Android, Web, UI/UX
189+
190+
---
191+
192+
## ๐Ÿ“ฒ Download
193+
194+
- [Official Website & Download](https://www.finditapp.me/)
195+
- [Android App Source Code](https://github.com/pratham-developer/FindIT)

0 commit comments

Comments
ย (0)