🏠 HomePulse Backend (API + MQTT + DB)

HomePulse Backend is the core of the smart-home platform.

It provides REST API endpoints, MQTT real-time processing, database storage, authentication, device management, and full Swagger documentation.

This backend communicates with ESP32 devices via MQTT and serves the frontend through REST API.

---

✨ Features

• Real-time IoT device monitoring (MQTT)
• ESP32 sensor data (temperature, humidity, motion, relay, etc.) from MQTT topics
• Full CRUD for Homes, Rooms, Devices
• JWT authentication
• MongoDB + Mongoose models
• REST API with validation
• Swagger API documentation
• Clean modular file structure

---

🗂 Project Structure

backend/
  └── src/
      ├── config/
      ├── controllers/
      ├── middlewares/
      ├── models/
      ├── routes/
      ├── utils/
      ├── validators/
      ├── db.ts
      ├── seed.ts
      ├── server.ts
      └── swagger.config.ts

Each folder is responsible for a clean separation of business logic:

• controllers – API logic
• routes – endpoints
• models – Mongoose schemas
• middlewares – validation/auth
• validators – request validation
• utils – helpers
• config – server configuration

---

📌 User Flow

After authentication, each user can:

• Create/manage Homes
• Create/manage Rooms
• Add devices to any room
• View real-time device data

---

Homes

Users may create any number of homes.

Home actions:

• ➕ Add Home
• ❌ Delete Home Each home contains multiple rooms.

---

Rooms

A room belongs to a home. Users can create unlimited rooms.

Room actions:

• ➕ Add Room
• Upload 3D splat file
• ❌ Delete Room

Rooms act as containers for devices and 3D positioning.

---

Devices

Devices are assigned directly to rooms.

Each device includes:

• Name
• Type
• Assigned room
• Online/offline state
• Live MQTT data

---

🔌 MQTT Communication

HomePulse uses MQTT as the real-time backbone.

Device lifecycle

• Device connects to MQTT
• Publishes sensor data
• Backend receives it via MQTT client
• Backend updates MongoDB + broadcasts to frontend

Data flow:

IoT Device → MQTT Broker → Backend → MongoDB → Frontend (3D view)

---

🔐 Authentication

• Login
• Registration
• Protected routes
• JWT stored securely

---

🛠 Tech Stack (Backend)

• Node.js
• Express
• MongoDB + Mongoose
• MQTT (Mosquitto / EMQX)
• JWT
• Swagger

Extra:

• MongoDB (local or cloud)
• MQTT broker

---

💻 Installation & Setup

🧬 Clone repo

git clone https://github.com/Home-Pulse-App/backend.git
cd backend

🧱 Backend setup

npm install
npm run dev

🧩 Environment variables

Your .env file must include:

PORT=3000
MONGO_URI=mongodb://localhost:27017/homepulse
MQTT_BROKER_URL=mqtt://localhost:1883
MQTT_USERNAME=
MQTT_PASSWORD=
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d

🍃 MongoDB setup

The backend uses Mongoose to handle:

• Users
• Houses
• Rooms
• Devices
• Sensor readings (optional depending on your model)

📡 MQTT setup

The backend connects to the broker defined in .env and subscribes to:

homepulse/{deviceId}/data homepulse/{deviceId}/status

---

📘 API Documentation (Swagger)

The backend provides full Swagger documentation describing all API endpoints:

What’s included:

• Full endpoint list
• Request/response schemas
• Validation rules
• JWT authentication documentation
• Error codes
• Example inputs/outputs

Access Swagger UI: /api/docs

Full list 🔗 : http://localhost:3000/api-docs

You can test APIs directly in the browser, explore descriptions, and validate integrations.

---

🧪 Testing

npm run test

Unit tests use:

• Jest or Vitest
• Supertest for API routes

---

🧾 Seed

The seed script populates the database with mock data.

The mock data is stored in the mockData directory.

The seed script will create:

• 1 user
• 1 house
• 1 room
• 1 splatFile
• 1 device
• 30050 sensor readings

To login use the following credentials:

email: user@email.com password: Secret123!

npm run seed

---

🚀 Deployment

You can deploy via:

• Docker (recommended)
• PM2 + Node
• Railway / Render / Fly.io
• Raspberry Pi (local server)