PneumoDetect Backend# 🫁 PneumoDetect Backend

AI-powered pneumonia detection system backend built with NestJS and TypeScript.

AI-Powered Pneumonia Detection System

Overview A production-ready NestJS backend for intelligent X-ray analysis

PneumoDetect is a comprehensive backend API for detecting pneumonia from chest X-ray images using AI/ML models. It provides user authentication, patient management, scan processing, and analytics capabilities.

Tech Stack

Framework: NestJS 11+
Language: TypeScript
Database: PostgreSQL 15 (Prisma ORM)
Authentication: JWT
File Storage: Cloudinary
Email: Nodemailer (Gmail SMTP)---
API Documentation: Swagger/OpenAPI

📋 Overview

Prerequisites

PneumoDetect Backend is a comprehensive REST API built with NestJS, TypeScript, and PostgreSQL. It provides:

Node.js 20+
PostgreSQL 15+✅ Authentication & Authorization - JWT-based access control with role-based permissions
npm or yarn✅ Patient Management - Complete patient record system with unique ID tracking

✅ Scan Management - X-ray upload, storage, and processing capabilities

Environment Variables✅ Mock AI Processing - AI result generation (PNEUMONIA/NORMAL) with confidence scores

✅ Dashboard Analytics - Real-time statistics aggregation for mobile dashboards

Create a .env file in the root directory:✅ Notifications - Real-time user notifications with automatic triggers

✅ Type-Safe - 100% TypeScript with zero build errors


DATABASE_URL=postgresql://postgres:postgres@localhost:5434/pneumodetect

JWT_SECRET=your-secret-key-here---

PORT=3000

## 🚀 Quick Start

CLOUDINARY_CLOUD_NAME=your-cloudinary-name

CLOUDINARY_API_KEY=your-cloudinary-api-key### Prerequisites

CLOUDINARY_API_SECRET=your-cloudinary-api-secret

- Node.js 18+

EMAIL_USER=your-email@gmail.com- PostgreSQL 15 (running on port 5434)

EMAIL_PASSWORD=your-app-password- npm or yarn

Installation

```bash# 1. Clone repository

# Install dependenciesgit clone <repo-url>

npm installcd pneumodetect-backend



# Generate Prisma Client# 2. Install dependencies

npx prisma generatenpm install



# Run migrations# 3. Setup environment variables

npx prisma migrate devcp .env.example .env

```# Edit .env with your database credentials



## Running the Application# 4. Run database migrations

npx prisma migrate dev

```bash

# Development mode with auto-reload# 5. Start development server

npm run start:devnpm run start:dev

Production build

npm run build### Quick Test (30 seconds)

npm run start

# Watch mode# 1. Get JWT token

npm run start:watchTOKEN=$(curl -s -X POST http://localhost:3000/auth/login \

```  -H "Content-Type: application/json" \

  -d '{"email":"doctor@hospital.com","password":"Pass123!"}' \

The server will start at `http://localhost:3000`  | jq -r '.access_token')



## API Documentation# 2. Test protected endpoint

curl -X GET http://localhost:3000/users/profile \

Swagger API documentation is available at `http://localhost:3000/api`  -H "Authorization: Bearer $TOKEN"



## Project Structure# Done! ✅


src/---

├── auth/              # Authentication & JWT

├── users/             # User management## 📦 7 Complete Modules

├── patients/          # Patient records

├── scans/             # X-ray scan processing### 1. Auth Module

├── analytics/         # Statistics & reportingJWT-based authentication with role-based access control.

├── notifications/     # User notifications```

├── admin/             # Admin operationsPOST   /auth/register         - Register new user

├── mail/              # Email servicePOST   /auth/login            - Login and get JWT token

├── prisma/            # Database servicePOST   /auth/refresh          - Refresh JWT token

└── main.ts            # Application entry pointGET    /auth/me               - Get current user info

Key Features### 2. Users Module

User profile management and information retrieval.

Authentication```

User registration with email OTP verificationGET /users/profile - Get current user profile
6-digit OTP with 10-minute expiryPATCH /users/profile - Update user profile
JWT-based session management (7-day tokens)GET /users - List all users (admin)
Login restricted to verified usersGET /users/:id - Get user by ID


### Scan Management

- Upload X-ray images to Cloudinary### 3. Admin Module

- Process scans with AI resultsAdministrative operations and system management.

- Track scan status (UPLOADED, PROCESSING, COMPLETED, FAILED)```

- Generate confidence scores and heatmapsPATCH  /admin/users/:id/role  - Change user role

GET    /admin/stats           - System statistics

### User ManagementDELETE /admin/users/:id       - Delete user

- Role-based access (ADMIN, CLINICIAN)```

- User profiles with avatars

- Active/inactive status management### 4. Patients Module

Patient record management and tracking.

### Analytics```

- Real-time statistics dashboardPOST   /patients              - Create patient

- Scan metrics by statusGET    /patients              - List all patients

- User activity trackingGET    /patients/:id          - Get patient by ID

- Performance analyticsPATCH  /patients/:id          - Update patient

Notifications

Real-time scan completion alerts### 5. Scans Module
System notificationsX-ray scan management with file uploads and processing.
Mark as read/unread```
Bulk operationsPOST /scans/upload - Upload X-ray image

GET /scans - List scans (role-filtered)

Database SchemaGET /scans/:id - Get scan by ID

POST /scans/:id/process - Process scan with AI

Key models:```

User: Authentication & profile
Patient: Patient information### 6. Analytics Module
Scan: X-ray images and AI resultsDashboard statistics and metrics aggregation.
Notification: User alerts```
Audit: Admin actionsGET /analytics/stats - Get dashboard statistics


## API Endpoints

### 7. Notifications Module ⭐ NEW

### AuthReal-time notifications with automatic triggers.

- `POST /auth/register` - Register new user```

- `POST /auth/login` - Login with email/passwordGET    /notifications         - Get all notifications

- `POST /auth/verify-otp` - Verify email with OTPGET    /notifications/:id     - Get single notification

- `POST /auth/resend-otp` - Resend OTPPATCH  /notifications/:id/read - Mark as read/unread

- `GET /auth/me` - Get current user (requires JWT)POST   /notifications         - Create notification

POST   /notifications/mark-all-read - Mark all as read

### ScansDELETE /notifications/:id     - Delete notification

- `POST /scans/upload` - Upload new scan```

- `POST /scans/:id/process` - Process scan

- `GET /scans` - List scans---

- `GET /scans/:id` - Get scan details

## 🛠️ Development

### Patients

- `POST /patients` - Create patient### Available Commands

- `GET /patients` - List patients

- `GET /patients/:id` - Get patient details```bash

- `PATCH /patients/:id` - Update patient# Development mode (with hot reload)

npm run start:dev

### Analytics

- `GET /analytics/stats` - Get statistics# Production build

npm run build

### Admin

- `GET /admin/users` - List all users# Production mode

- `PATCH /admin/users/:id/status` - Update user statusnpm run start:prod

- `DELETE /admin/users/:id` - Delete user

# Run tests

## Testingnpm run test



```bash# Run e2e tests

# Run testsnpm run test:e2e

npm run test

# Lint code

# Run e2e testsnpm run lint

npm run test:e2e

```# Format code

npm run format

## Email Configuration```



The system uses Nodemailer with Gmail SMTP. To enable:### Database



1. Generate an [App Password](https://myaccount.google.com/apppasswords) from Google Account```bash

2. Add to `.env`:# Create new migration

   ```npx prisma migrate dev --name <migration_name>

   EMAIL_USER=your-email@gmail.com

   EMAIL_PASSWORD=your-app-password# View database UI

   ```npx prisma studio



## Database Migrations# Reset database (⚠️ deletes all data)

npx prisma migrate reset

```bash```

# Create migration

npx prisma migrate dev --name migration-name---



# View database## 🏗️ Architecture

npx prisma studio

┌─────────────────────────────────────┐

Error Handling│ Mobile App (React Native) │

│ - Login/Register │

Proper HTTP status codes│ - Patient Management │
Detailed error messages│ - Scan Upload & Results │
Input validation with class-validator│ - Dashboard & Notifications │
Exception filters for consistent responses└──────────────┬──────────────────────┘
```
         │ HTTP REST API
```

Security┌──────────────▼──────────────────────┐

│ NestJS Backend (port 3000) │

Password hashing with bcrypt (10 rounds)├─────────────────────────────────────┤
JWT token expiry (7 days)│ 7 Modules: │
Email verification required before login│ ✅ Auth (JWT) │
OTP validation with expiry│ ✅ Users (Profiles) │
Role-based access control│ ✅ Admin (Management) │
Protected routes with JwtAuthGuard│ ✅ Patients (Records) │

│ ✅ Scans (X-rays) │

Contributing│ ✅ Analytics (Dashboard) │

│ ✅ Notifications (Alerts) │

Create a feature branch└──────────────┬──────────────────────┘
Make your changes │ SQL
Ensure tests pass┌──────────────▼──────────────────────┐
Submit a pull request│ PostgreSQL 15 Database │

│ (localhost:5434) │

License└─────────────────────────────────────┘


Proprietary - PneumoDetect

---

## 🔐 Security Features

✅ **JWT Authentication** - All endpoints require valid JWT token
✅ **Role-Based Access Control** - CLINICIAN and ADMIN roles
✅ **Owner-Only Access** - Users can only access their own data
✅ **Password Hashing** - Bcrypt for secure storage
✅ **Input Validation** - DTO validation on all endpoints
✅ **CORS Support** - Configured for mobile requests
✅ **Type Safety** - 100% TypeScript, no `any` types

---

## 📊 Data Models

### User
```typescript
{
  id: UUID
  email: string (unique)
  password: string (hashed)
  name: string
  role: 'ADMIN' | 'CLINICIAN'
  specialization?: string
  phone?: string
  createdAt: DateTime
  updatedAt: DateTime
}

Patient

{
  id: UUID
  idNumber: string (unique)
  name: string
  age: number
  gender: 'MALE' | 'FEMALE'
  createdAt: DateTime
  updatedAt: DateTime
}

Scan

{
  id: UUID
  imageUrl: string
  status: 'UPLOADED' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
  result?: 'PNEUMONIA' | 'NORMAL'
  confidence?: number (0.0-1.0)
  patientId: UUID
  doctorId: UUID
  createdAt: DateTime
  updatedAt: DateTime
}

Notification

{
  id: UUID
  title: string
  message: string
  type: 'SCAN' | 'SYSTEM' | 'USER'
  read: boolean
  userId: UUID
  createdAt: DateTime
  updatedAt: DateTime
}

📚 Documentation

Getting Started

Quick Start Guide - 5-minute setup
Complete System Overview - Full architecture

API Documentation

Notifications API - Detailed endpoint reference
API Testing Guide - 20+ test scenarios with curl

Architecture & Diagrams

System Architecture - Visual diagrams
Implementation Details - Module breakdown

🧪 Testing

Test Notifications Endpoint

# Get JWT token
TOKEN=$(curl -s -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"doctor@hospital.com","password":"Pass123!"}' \
  | jq -r '.access_token')

# Get all notifications
curl -X GET http://localhost:3000/notifications \
  -H "Authorization: Bearer $TOKEN" | jq .

# Create notification
curl -X POST http://localhost:3000/notifications \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test",
    "message": "Test notification",
    "type": "SYSTEM",
    "userId": "user-id"
  }'

# Mark as read
curl -X PATCH http://localhost:3000/notifications/:id/read \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read": true}'

Comprehensive Testing

See NOTIFICATIONS_TESTING_GUIDE.md for 20+ test scenarios including:

Authorization tests
Validation tests
Integration tests
Performance tests

📱 Mobile Integration

Fetch Notifications (React Native)

const [notifications, setNotifications] = useState([]);
const [unreadCount, setUnreadCount] = useState(0);

useEffect(() => {
  const fetchNotifications = async () => {
    const res = await fetch('http://localhost:3000/notifications', {
      headers: { Authorization: `Bearer ${token}` }
    });
    const data = await res.json();
    setNotifications(data.data);
    setUnreadCount(data.unreadCount);
  };

  fetchNotifications();
  const interval = setInterval(fetchNotifications, 10000); // Poll every 10s
  return () => clearInterval(interval);
}, [token]);

🔧 Environment Variables

Create a .env file in the root directory:

# Database
DATABASE_URL=postgresql://user:password@localhost:5434/pneumodetect

# JWT
JWT_SECRET=your_super_secret_key_here
JWT_EXPIRES_IN=7d

# Application
NODE_ENV=development
PORT=3000

# File Upload
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760

📊 Build Status

✅ TypeScript Compilation: SUCCESS (0 errors)
✅ Module Integration: COMPLETE
✅ Type Safety: 100%
✅ Production Ready: YES

🚀 Deployment

Docker

# Build Docker image
docker-compose build

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

Environment Setup

For production, update .env with:

Real database credentials
Strong JWT secret
Production database URL
Appropriate logging levels

📞 Support & Resources

Documentation Files

NOTIFICATIONS_QUICKSTART.md - Quick start guide
NOTIFICATIONS_DOCUMENTATION.md - Complete API reference
NOTIFICATIONS_TESTING_GUIDE.md - Testing guide with examples
NOTIFICATIONS_ARCHITECTURE_DIAGRAMS.md - System architecture
BACKEND_COMPLETE_README.md - Full system overview

Common Issues

"Cannot connect to database"

Ensure PostgreSQL is running on port 5434
Check DATABASE_URL in .env file
Run migrations: npx prisma migrate dev

"JWT Token Invalid"

Get new token from /auth/login
Include in Authorization header: Bearer TOKEN

"Module not found"

Run npm install
Rebuild: npm run build

📝 Git Workflow

# Create new feature branch
git checkout -b feature/your-feature-name

# Make changes and commit
git add .
git commit -m "feat: describe your changes"

# Push to GitHub
git push origin feature/your-feature-name

# Create Pull Request on GitHub

✅ Quality Assurance

✅ TypeScript - Full type safety, zero any types
✅ Testing - 20+ test scenarios provided
✅ Documentation - 10 comprehensive guides (~110 KB)
✅ Error Handling - Proper HTTP status codes
✅ Security - JWT auth on all endpoints
✅ Code Quality - NestJS best practices

📜 License

MIT License - See LICENSE file for details

🎉 Summary

PneumoDetect Backend provides a complete, production-ready REST API with:

✨ 7 fully integrated modules ✨ 26+ API endpoints (all protected) ✨ Complete notification system ✨ Real-time capable architecture ✨ 100% type-safe TypeScript ✨ Comprehensive documentation ✨ Zero build errors

Ready for production deployment! 🚀

Last Updated: April 16, 2026 Status: ✅ Production Ready Build: ✅ Successful (0 errors)

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
prisma		prisma
src		src
test		test
.gitignore		.gitignore
.prettierrc		.prettierrc
AUTH_COMPLIANCE_REPORT.md		AUTH_COMPLIANCE_REPORT.md
BACKEND_PAYLOAD_REFERENCE.md		BACKEND_PAYLOAD_REFERENCE.md
COMPLIANCE_SUMMARY.md		COMPLIANCE_SUMMARY.md
ENDPOINT_VALIDATION_CHECKLIST.md		ENDPOINT_VALIDATION_CHECKLIST.md
FLASK_AI_INTEGRATION_GUIDE.md		FLASK_AI_INTEGRATION_GUIDE.md
FULL_APP_COMPLIANCE_REPORT.md		FULL_APP_COMPLIANCE_REPORT.md
REACT_NATIVE_INTEGRATION_GUIDE.md		REACT_NATIVE_INTEGRATION_GUIDE.md
README.md		README.md
check-otp.js		check-otp.js
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
nest-cli.json		nest-cli.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

PneumoDetect Backend# 🫁 PneumoDetect Backend

Overview A production-ready NestJS backend for intelligent X-ray analysis

Tech Stack

📋 Overview

Prerequisites

Environment Variables✅ Mock AI Processing - AI result generation (PNEUMONIA/NORMAL) with confidence scores

Installation

Installation

Production build

Key Features### 2. Users Module

Authentication```

Notifications

Database SchemaGET /scans/:id - Get scan by ID

Error Handling│ Mobile App (React Native) │

Security┌──────────────▼──────────────────────┐

Contributing│ ✅ Analytics (Dashboard) │

License└─────────────────────────────────────┘

Patient

Scan

Notification

📚 Documentation

Getting Started

API Documentation

Architecture & Diagrams

🧪 Testing

Test Notifications Endpoint

Comprehensive Testing

📱 Mobile Integration

Fetch Notifications (React Native)

🔧 Environment Variables

📊 Build Status

🚀 Deployment

Docker

Environment Setup

📞 Support & Resources

Documentation Files

Common Issues

📝 Git Workflow

✅ Quality Assurance

📜 License

🎉 Summary

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages