🍽️ SupplyBridge — Backend API

B2B Restaurant Community Support Connect. Request. Fulfill. Together.

SupplyBridge is a real-time collaboration platform designed exclusively for restaurant owners and food service vendors. It enables instant Pings (urgent supply requests), secure Connections, and Live Chat to keep kitchens running smoothly.

---

📬 API Documentation

Full API reference with request/response examples available on Postman.

---

📌 Table of Contents

• Core Features
• Tech Stack
• System Architecture
• Prerequisites
• Environment Variables
• Installation & Local Setup
• Database Setup (Prisma + MongoDB)
• Running the Application
• WebSocket Events (Real-time Chat)
• Background Jobs (BullMQ)
• Project Structure
• API Documentation
• Deployment
• Contributing
• License

---

🚀 Core Features

Module	Description
🔔 Ping System	Geolocation-based urgent supply requests. Filter by radius, category, and urgency level (Emergency, Moderate, General).
🤝 Connection Management	LinkedIn-style connection flow (Send Request → Accept/Reject → Trusted Network).
💬 Real-time Chat	WebSocket powered P2P messaging with Redis caching. Supports text, images, and file sharing.
👥 User Profiles	Dual-role support (Vendor/Restaurant). Multi-step registration with email OTP verification.
🔐 Auth & Security	JWT authentication, Social Login (Google/Apple), Bcrypt password hashing, and Role-Based Access Control (RBAC).
📬 Notifications	Multi-channel support: In-App DB notifications + Push Notifications (Firebase Cloud Messaging).
⚙️ Background Workers	Asynchronous processing for Emails, Image Uploads, and Bulk Notifications via BullMQ + Redis.

---

🛠 Tech Stack

Category	Technology	Purpose
Runtime	Node.js (v18+)	JavaScript Runtime
Language	TypeScript	Static Typing
Framework	Express.js	REST API Layer
Realtime	WebSocket (ws)	Live Chat & Connection Events
Database	MongoDB	Primary Data Store
ORM	Prisma	Type-safe Database Queries
Cache	Redis	OTP Storage, Chat Cache, Queue Backend
Queue	BullMQ	Email & Notification Workers
Storage	AWS S3 / DigitalOcean Spaces	User Avatars & Chat Media
Push Notif	Firebase Admin SDK	Multi-device Push Notifications
Payments	Stripe	(Planned) Premium Features

---

🧠 System Architecture

[Client App]
    │
    ├── REST (Express) ───────> Prisma ORM ───────> MongoDB
    │         │
    │         └── BullMQ ──────> Redis ──────> Workers (Email, Image, Notify)
    │
    └── WebSocket (ws) ────────> Redis (Chat Cache)

---

📋 Prerequisites

Ensure you have the following installed on your system:

• Node.js v18.x or later
• npm or bun (project uses bun.lockb alongside package-lock.json)
• MongoDB (Local or Atlas URI)
• Redis (Local or Cloud)

---

🔐 Environment Variables

Create a .env file in the root directory. Copy the contents of .env.example (create one if missing) and fill in the values.

# ------------------------------
# Server
# ------------------------------
PORT=5000
NODE_ENV=development

# ------------------------------
# Database
# ------------------------------
DATABASE_URL="mongodb+srv://<user>:<pass>@cluster.mongodb.net/SupplyBridge"

# ------------------------------
# JWT & Security
# ------------------------------
JWT_SECRET="your-super-secret-jwt-key"
JWT_EXPIRES_IN="30d"
BCRYPT_SALT_ROUNDS=12

# ------------------------------
# Redis
# ------------------------------
REDIS_HOST="127.0.0.1"
REDIS_PORT=6379
REDIS_PASSWORD="optional_redis_password"

# ------------------------------
# Email (Nodemailer)
# ------------------------------
SMTP_HOST="smtp.gmail.com"
SMTP_PORT=587
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"

# ------------------------------
# Firebase (Push Notifications)
# ------------------------------
FIREBASE_PROJECT_ID="supplybridge-xxxx"
FIREBASE_CLIENT_EMAIL="firebase-adminsdk@....iam.gserviceaccount.com"
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."

# ------------------------------
# Storage (AWS S3 / Spaces)
# ------------------------------
SPACES_ENDPOINT="nyc3.digitaloceanspaces.com"
SPACES_KEY="ACCESS_KEY"
SPACES_SECRET="SECRET_KEY"
SPACES_BUCKET="supplybridge-media"

# ------------------------------
# Stripe (Optional)
# ------------------------------
STRIPE_SECRET_KEY="sk_test_..."

---

💻 Installation & Local Setup

1. Clone the repository

git clone https://github.com/your-org/supplybridge-backend.git
cd supplybridge-backend

---

2. Install dependencies

npm install
# or if you use bun
bun install

3. Set up environment variables

cp .env.example .env
# Edit .env with your local credentials (Database URL, Redis, etc.)

---

🗄️ Database Setup (Prisma + MongoDB)

1. Generate Prisma Client

npx prisma generate

2. Push Schema to Database

Note: prisma db push is recommended for development. For production, use prisma migrate deploy.

npx prisma db push

3. (Optional) Seed the Database

# Create a seed script in prisma/seed.ts and run:
npx prisma db seed

---

🏃 Running the Application

SupplyBridge uses Concurrently to run the main server and three background workers in a single terminal window.

Development Mode (Hot Reload):

npm run dev

This starts:

• 🟢 API Server (src/server.ts)
• 🔵 Email Worker (src/jobs/workers/emailWorker.ts)
• 🟡 Notification Worker
• 🟣 Image Upload Worker

Production Build:

npm run build
npm run start

---

🔌 WebSocket Events (Real-time Chat)

The WebSocket server runs on the same HTTP port as Express (/ws path or native upgrade).

Event	Direction	Description
subscribe-room	Client → Server	Join a specific chat room.
send-message	Client → Server	Send text or file URL to a room.
new-message	Server → Client	Broadcasted message to all room members.
typing	Bidirectional	Typing indicator events.
conversations	Server → Client	Initial payload with recent chat list.

Connection Header:

• token: <JWT_ACCESS_TOKEN> (required)

---

⚙️ Background Jobs (BullMQ)

We utilize Bull Board for monitoring queues in development.

• URL: http://localhost:5000/admin/queues
• Queues:
  1. EmailQueue — Account verification, password reset.
  2. NotificationQueue — Sending push notifications to FCM.
  3. ImageQueue — Processing and uploading profile/business images to cloud storage.

---

📁 Project Structure

src/
├── app/
│   ├── middlewares/   # Auth, Validation, Error Handling
│   └── modules/       # Feature-based modules (User, Ping, Chat, Connection)
├── config/            # App configuration & Service Accounts
├── errors/            # Custom error classes & Handlers
├── helpers/           # Reusable utilities (JWT, Bcrypt, FileUploader)
├── jobs/              # BullMQ Queues, Workers, and BullBoard UI
├── shared/            # Prisma Client, Redis Client, Logger, Pagination Helpers
├── app.ts             # Express App Initialization
└── server.ts          # Entry Point (Starts HTTP & WebSocket Server)

---

📖 API Documentation

Once the server is running locally, you can access the detailed API documentation via Postman or the .http files inside each module folder.

Postman Collection: Import the collection from src/app/middlewares/postman.ts or use the generated OpenAPI spec.

Base URL

http://localhost:5000/api/v1

Core Endpoints

Method	Endpoint	Description
POST	/auth/login	Email/Password Login
POST	/user/create	Register Pending User (Sends OTP)
GET	/ping	Get nearby active pings (Geo-filtered)
POST	/ping/create	Create a new supply request
GET	/connection/my	List my trusted vendors
GET	/chat/conversations	Get recent chat history

---

🚢 Deployment

Recommended Stack

• Hosting: AWS EC2 / DigitalOcean Droplet / Railway
• Database: MongoDB Atlas
• Redis: Upstash / Redis Labs
• Process Manager: PM2

PM2 Deployment Script

An ecosystem.config.js is included in the root.

# Install PM2 globally
npm install pm2 -g

# Build the project
npm run build

# Start in production cluster mode
pm2 start ecosystem.config.js --env production

---

🤝 Contributing

We welcome contributions! Please follow the standard Git Flow.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Code Style: Ensure you run npm run build locally to check for TypeScript errors before committing.

---

📄 License

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

---

Built with ❤️ for the restaurant community. Got questions? Reach out to the backend team lead.

📂 Project Information

📝 Detail	📌 Value
🔗 GitHub URL	https://github.com/shahjalal-labs/supply_bridge_backend
🌐 Live Site	postman api document
💻 Portfolio GitHub	https://github.com/shahjalal-labs/shahjalal-portfolio-v2
🌐 Portfolio Live	http://shahjalal-labs.surge.sh
📅 Created On	09/04/2026 04:30 PM Thu GMT+6
📍 Location	Sharifpur, Gazipur, Dhaka
💼 LinkedIn	https://www.linkedin.com/in/shahjalal-labs/
📘 Facebook	https://www.facebook.com/shahjalal.labs
▶️ Twitter	https://x.com/shahjalal_labs
🔒 Visibility	Public 🌍

---

Developer info: