Blind Enhancement and Assistive Cap with Optical Navigation
BEACON is a companion system designed to support visually impaired individuals by working in tandem with a smart wearable cap. The cap is equipped with a camera module (ESP32-CAM) that performs real-time object detection, crosswalk recognition, currency identification, and proximity alerts — all powered by AI models running on a separate camera service.
This repository contains the backend API server — the central nervous system that ties the entire BEACON ecosystem together. It handles:
- 🔐 User authentication & management — Registration, login, and JWT-secured sessions
- 🆘 Emergency alerting — Automated fall detection emails and manual SOS alerts sent to emergency contacts with Google Maps location links
- 📇 Emergency contact management — Full CRUD with priority ordering for contacts who receive alerts
- 📋 Task scheduling — Repeatable and one-time task reminders with trigger tracking to help users manage daily routines
- 📨 Message queues — Bi-directional message relay between the camera module and the mobile app, enabling real-time data transmission
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ BEACON Cap │ │ BEACON Backend │ │ BEACON Mobile │
│ (ESP32-CAM + │◄───►│ (This Repo) │◄───►│ (Expo App) │
│ AI Service) │ │ │ │ │
│ │ │ ┌────────────┐ │ │ • Voice UI │
│ • Object Det. │ │ │ Fastify │ │ │ • Navigation │
│ • Crosswalk │ │ │ REST API │ │ │ • Task Mgmt │
│ • Currency │ │ ├────────────┤ │ │ • SOS Trigger │
│ • Proximity │ │ │ PostgreSQL │ │ │ │
│ │ │ │ (Prisma) │ │ │ │
│ │ │ ├────────────┤ │ │ │
│ │ │ │ Nodemailer │ │ │ │
│ │ │ │ (Alerts) │ │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
The backend acts as the bridge between the smart cap and the mobile application. The camera service pushes detection results into message queues via the API, and the mobile app consumes them to deliver voice-guided audio feedback to the user.
| Layer | Technology |
|---|---|
| Runtime | Node.js with TypeScript |
| Framework | Fastify v5 — high-performance HTTP server |
| ORM | Prisma v7 — type-safe database client |
| Database | PostgreSQL |
| Auth | JWT (jsonwebtoken) + bcrypt password hashing |
| Nodemailer (Gmail SMTP) — HTML-styled emergency alerts | |
| Docs | Swagger / OpenAPI 3.0 with Swagger UI (/docs) |
| Logging | Pino with pino-pretty transport |
| Code Quality | ESLint + Prettier + Husky pre-commit hooks + lint-staged |
| Build | tsx (dev) / tsc (production) |
All endpoints except public routes require a Bearer JWT token in the Authorization header.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /auth/register |
Register a new user | ❌ |
| POST | /auth/login |
Login and receive a JWT token | ❌ |
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /emergency |
Send a generic emergency email with location | ✅ |
| POST | /emergency/alerts/fall |
Send fall-detection alert to primary emergency contact | ✅ |
| POST | /emergency/alerts/manual |
Manually trigger an SOS alert with GPS coordinates | ✅ |
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /emergency-contact |
Create a new emergency contact | ✅ |
| GET | /emergency-contact/:id |
Get a specific emergency contact | ✅ |
| GET | /emergency-contact/list |
List contacts with pagination | ✅ |
| PATCH | /emergency-contact/:id |
Update an emergency contact | ✅ |
| DELETE | /emergency-contact/:id |
Delete an emergency contact | ✅ |
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /tasks |
Create a new task (one-time or recurring) | ✅ |
| GET | /tasks |
List all tasks for the authenticated user | ✅ |
| GET | /tasks/due |
Fetch tasks due at the current time | ✅ |
| PATCH | /tasks/:id |
Toggle task active/inactive status | ✅ |
| POST | /tasks/trigger/:id |
Mark a task as triggered (update lastTriggered) | ✅ |
| DELETE | /tasks/:id |
Delete a task | ✅ |
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /message-queues |
Create a new message in the queue | ✅ |
| POST | /message-queues/public |
Create a message (public — used by cam service) | ❌ |
| GET | /message-queues |
List all messages for the authenticated user | ✅ |
| DELETE | /message-queues/:id |
Delete a message from the queue | ✅ |
📘 Interactive API docs are available at
http://localhost:8080/docswhen the server is running.
┌──────────────┐ ┌─────────────────────┐
│ Users │────<│ EmergencyContacts │
│ │ │ │
│ id (cuid) │ │ id, userId, name │
│ email │ │ email, mobileNo │
│ name │ │ position (priority)│
│ password │ │ createdAt │
│ createdAt │ └─────────────────────┘
│ │
│ │────<┌─────────────────────┐
│ │ │ Tasks │
│ │ │ │
│ │ │ id, userId, name │
│ │ │ scheduledTime │
│ │ │ specificDate │
│ │ │ isActive │
│ │ │ isRepeating │
│ │ │ repeatDays[] │
│ │ │ lastTriggered │
│ │ └─────────────────────┘
│ │
│ │────<┌─────────────────────┐
│ │ │ MessageQueue │
│ │ │ │
│ │ │ id, userId │
│ │ │ message │
└──────────────┘ └─────────────────────┘
All relationships cascade on delete — removing a user automatically cleans up their contacts, tasks, and messages.
- Node.js ≥ 18
- PostgreSQL database
- Gmail account with an App Password for email alerts
git clone https://github.com/SabarishAV/beacon-backend.git
cd beacon-backendnpm installCopy the example env file and fill in your values:
cp .env.example .envPORT=8080
DATABASE_URL=postgresql://user:password@localhost:5432/beacon
EMAIL_USERNAME=your-email@gmail.com
EMAIL_APP_PASSWORD=your-gmail-app-password
JWT_SECRET=your-secret-key# Generate Prisma client
npm run prisma:generate
# Run database migrations
npm run prisma:migratenpm run devThe server will start at http://localhost:8080 with hot-reload enabled.
| Script | Description |
|---|---|
npm run dev |
Start dev server with hot-reload (tsx watch) |
npm run build |
Compile TypeScript to JavaScript |
npm run lint |
Run ESLint on all source files |
npm run lint:fix |
Run ESLint with auto-fix |
npm run format |
Format all source files with Prettier |
npm run prisma:generate |
Generate Prisma client from schema |
npm run prisma:studio |
Open Prisma Studio (visual DB editor) |
npm run prisma:migrate |
Run pending database migrations |
npm run prisma:reset |
Reset database and re-run all migrations |
npm run seed:up |
Run database seeders |
npm run seed:down |
Reverse database seeders |
beacon_backend/
├── prisma/
│ ├── schema.prisma # Database schema definition
│ ├── migrations/ # SQL migration files
│ └── seeders/ # Database seed scripts
│ ├── up.ts
│ └── down.ts
├── src/
│ ├── server.ts # Application entry point
│ ├── config/
│ │ ├── logger.ts # Pino logger configuration
│ │ ├── prisma.ts # Prisma client singleton
│ │ └── swagger.ts # Swagger/OpenAPI setup
│ ├── constants/
│ │ ├── bcrypt.ts # Salt rounds configuration
│ │ └── route.ts # Public routes whitelist
│ ├── controllers/
│ │ ├── auth-controller.ts
│ │ ├── emergency-controller.ts
│ │ ├── emergency-contact-controllers.ts
│ │ ├── message-queue-controller.ts
│ │ └── tasks-controller.ts
│ ├── middlewares/
│ │ ├── error.ts # Global error handler (Prisma + custom errors)
│ │ └── jwt.ts # JWT authentication pre-handler
│ ├── repository/
│ │ ├── user-repository.ts
│ │ ├── emergency-contact-repository.ts
│ │ ├── message-queue-repository.ts
│ │ └── tasks-repository.ts
│ ├── routes/
│ │ ├── auth-route.ts
│ │ ├── emergency-route.ts
│ │ ├── emergency-contact-routes.ts
│ │ ├── message-queue-route.ts
│ │ └── task-route.ts
│ └── utils/
│ ├── date.ts # Date formatting helpers
│ ├── jwt.ts # JWT sign/verify utilities
│ ├── mail.ts # Email templates (fall alert, SOS)
│ ├── pagination.ts # Pagination helper
│ ├── time.ts # Time utilities
│ ├── errors/ # Custom error classes
│ │ ├── AppError.ts
│ │ ├── BadRequestError.ts
│ │ ├── ForbiddenError.ts
│ │ ├── NotFoundError.ts
│ │ └── ValidationError.ts
│ └── swagger-schemas/ # OpenAPI schema definitions
├── .env.example # Environment variable template
├── .prettierrc # Prettier configuration
├── eslint.config.mjs # ESLint configuration
├── tsconfig.json # TypeScript configuration
├── tsup.config.ts # tsup bundler configuration
└── package.json
| Repository | Description |
|---|---|
| beacon-mobile | React Native (Expo) mobile application — voice UI, navigation, task manager |
| beacon-camera | Python AI service — object detection, crosswalk & currency recognition |
MIT
Built with ❤️ for accessibility