BULDM

Backend service powering the BULDM (Bring Up Lost or Discovered Material) platform - a TypeScript/Express/MongoDB solution for lost/found item management with AI-powered features and real-time communication.

🔗 Frontend Repository: buldm_frontend

• Features
• Tech Stack
• Getting Started
• Environment Variables
• Project Structure
• Core API Endpoints
• Validation & Error Handling
• Deployment
• Contribution
• License =======

📋 Table of Contents

• 🚀 Key Features
• 🛠️ Tech Stack
• 🏗️ Project Structure
• 🚀 Getting Started
• 🔧 Environment Variables
• 🔌 Core API Endpoints
• ✅ Validation & Error Handling
• 🤝 Contribution
• 📜 License

🚀 Key Features

🔐 Identity Management

• JWT authentication with refresh tokens
• Google OAuth 2.0 integration
• Email verification with Resend API
• Password strength validation & reset flow
• Role-based access control (Admin/User)

📦 Post Management

• CRUD operations for lost/found items
• Geospatial queries with 2dsphere indexes
• Status tracking: lost → found → claimed
• Category-based filtering & search
• Contact information masking

📸 Intelligent Processing

• AI Item Prediction via Hugging Face API
• NSFW Detection using nsfwjs
• Cloudinary media storage with Multer
• Automated content moderation

💬 Real-time System

• Socket.IO powered messaging
• User-to-user chat channels
• Message persistence with read receipts
• Notification system (OneSignal)

⚙️ Operational Excellence

• Swagger API documentation

• Rate limiting protection

• Reporting system for users/posts

• Fuse.js fuzzy user search

• Robust error handling

• Reporting System

  • Users can report posts or other users

• Validation

  • Rigorous input validation via express-validator for all endpoints

• Robust Error Handling

  • Consistent JSON error responses with status codes and messages

---

Deployment

Deploying to Vercel

This project is configured for deployment on Vercel. Follow these steps to deploy:

1. Install Vercel CLI (if not already installed)

   npm install -g vercel

2. Login to Vercel

   vercel login

3. Build the project

   npm run build

4. Deploy to Vercel

   vercel

5. Set Environment Variables

   • Go to your Vercel project dashboard
   • Navigate to Settings > Environment Variables
   • Add all the required environment variables from .env.example

6. Production Deployment

   vercel --prod

The project is already configured with the necessary vercel.json file for proper routing and serverless function configuration.

• Extensible & Modular
  • Clean codebase with clear separation of concerns

---

Tech Stack

• Language: TypeScript
• Runtime: Node.js (Express)
• Database: MongoDB (via Mongoose)
• Authentication: JWT
• Email: MailerSend API
• Validation: express-validator
• File Uploads: multer
• Geospatial: MongoDB 2dsphere indexes

---

Getting Started

=======

🛠️ Tech Stack

Category	Technologies
Core	Node.js, Express, TypeScript
Database	MongoDB, Mongoose
Auth	JWT, OAuth2, bcrypt
Realtime	Socket.IO
AI Services	Hugging Face, nsfwjs
Media	Cloudinary, Multer
Validation	express-validator
Communication	Resend (Email), OneSignal (Push)
Utilities	Swagger, Fuse.js, Express Rate Limit

🏗️ Project Structure

buldm_backend/
├── src/
│   ├── controllers/      # Route handlers
│   ├── models/           # MongoDB schemas
│   ├── routes/           # Express routers
│   ├── middleware/       # Auth, validation, etc.
│   ├── services/         # Business logic
│   ├── utils/            # Helpers & utilities
│   └── config/           # Configuration setup
├── public/               # Static assets
├── swagger/              # API documentation specs
├── .env.sample           # Environment template
├── package.json
└── tsconfig.json

🚀 Getting Started

Prerequisites

• Node.js v20+
• MongoDB Atlas cluster
• Cloudinary account
• Resend API key

# Clone repository
git clone https://github.com/hazzemSaid/buldm_backend.git
cd buldm_backend

# Install dependencies
npm install

# Build and run
npm run build
npm start

# Development mode (hot reload)
npm run dev

🔧 Environment Variables

Create a .env file with:

# ======== CORE ========
PORT=5000
MONGODB_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/buldm
JWT_SECRET=your_secure_jwt_secret
REFRESH_TOKEN_SECRET=your_secure_refresh_secret

# ======== MEDIA ========
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_key
CLOUDINARY_API_SECRET=your_secret

# ======== SERVICES ========
RESEND_API_KEY=your_resend_key
SENDER_EMAIL=verified@email.com
ONESIGNAL_APP_ID=your_onesignal_app_id
ONESIGNAL_API_KEY=your_onesignal_key
HUGGING_FACE_API_TOKEN=your_token

🔌 Core API Endpoints

Method	Endpoint	Description	Auth
POST	/api/v1/user/register	Register new user	No
POST	/api/v1/user/login	User login	No
POST	/api/v1/user/verify	Verify email	No
POST	/api/v1/user/forgot-password	Request password reset	No
POST	/api/v1/user/reset-password	Reset password	No
GET	/api/v1/user/:id	Get user by ID	Yes
PUT	/api/v1/user/:id	Update user profile	Yes
POST	/api/v1/post	Create new post	Yes
GET	/api/v1/post	Search posts (geo/status)	Yes
PUT	/api/v1/post/:id	Update post	Yes
DELETE	/api/v1/post/:id	Delete post	Yes
POST	/api/v1/report	Submit report	Yes
POST	/api/v1/chat	Initiate chat	Yes

Most endpoints require Authorization: Bearer <token> header

✅ Validation & Error Handling

• Rigorous input validation via express-validator
• Unified error response format:

{
  "status": "error",
  "error": "Descriptive message",
  "statuscode": 400,
  "data": null
}

• Centralized error handlers for:
  • Authentication failures
  • Permission errors
  • Database constraints
  • Rate limiting

🤝 Contribution

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a pull request

📜 License

For usage and distribution terms, please contact the repository owner.