CrowdShield AI Backend

A comprehensive Node.js/TypeScript backend for real-time crowd management and safety monitoring during large-scale events.

Features

• Real-time Communication: Socket.IO for live updates and bidirectional communication
• MongoDB Integration: Geospatial data storage with TTL indexes for location pings
• AI/ML Integration: REST API integration with Python ML microservice
• Authentication: JWT-based authentication with role-based access control
• Alert System: Real-time alert generation and management
• Action Coordination: Emergency response action logging and notification
• Report Management: Incident reporting with auto-triage capabilities
• SMS/WhatsApp: Twilio integration for emergency notifications
• Comprehensive API: RESTful API with OpenAPI documentation

Architecture

Core Components

• Express.js Server: RESTful API with middleware for security, validation, and error handling
• Socket.IO: Real-time WebSocket communication for live updates
• MongoDB: Primary database with geospatial indexing and TTL collections
• Mongoose ODM: Schema-based modeling with validation and middleware
• JWT Authentication: Secure token-based authentication with refresh tokens
• Twilio Integration: SMS and WhatsApp emergency notifications

Data Models

• Users: Admin and staff accounts with role-based permissions
• Events: Event definitions with geospatial boundaries
• Zones: Sub-areas within events with polygon definitions
• LocationPings: Real-time location data with TTL expiration (15 minutes)
• Alerts: System-generated and manual alerts with severity levels
• Actions: Emergency response actions with multi-channel delivery
• Reports: Incident reports with auto-triage and attachment support
• AI Insights/Predictions: Cached ML service results

Installation

1. Clone and navigate to backend directory:

   cd backend

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration

4. Start MongoDB (if running locally):

   mongod

5. Seed the database:

   npm run seed

6. Start the development server:

   npm run dev

The server will start on http://localhost:8080

Environment Variables

Required

• MONGO_URI: MongoDB connection string
• JWT_SECRET: Secret key for JWT tokens (minimum 32 characters)
• FRONTEND_ORIGIN: Frontend URL for CORS

Optional

• PORT: Server port (default: 8080)
• ML_BASE: ML service base URL (default: http://localhost:5001)
• TWILIO_ACCOUNT_SID: Twilio account SID for SMS/WhatsApp
• TWILIO_AUTH_TOKEN: Twilio auth token
• TWILIO_FROM: Twilio phone number
• REDIS_URL: Redis connection for caching (optional)

API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/me - Get current user profile
• PATCH /api/auth/me - Update user profile
• POST /api/auth/change-password - Change password

Map Data

• GET /api/map-data - Get live map data with density
• POST /api/map-data/ping - Add location ping
• GET /api/map-data/history/:eventId - Get location history
• GET /api/map-data/density/:eventId/:zoneId - Get zone density

Alerts

• GET /api/alerts - Get alerts with filtering
• POST /api/alerts - Create new alert
• PATCH /api/alerts/:id/resolve - Resolve alert
• GET /api/alerts/stats/:eventId - Get alert statistics

AI Integration

• GET /api/ai-insights - Get latest AI insights
• GET /api/ai-predictions - Get AI predictions
• POST /api/ai-insights/refresh - Refresh insights from ML service
• POST /api/ai-predictions/refresh - Refresh predictions

Actions

• GET /api/actions - Get emergency actions
• POST /api/actions - Create new action
• GET /api/actions/templates - Get emergency action templates
• GET /api/actions/stats/:eventId - Get action statistics

Reports

• GET /api/reports - Get incident reports
• POST /api/reports - Submit new report (supports anonymous)
• PATCH /api/reports/:id/status - Update report status
• GET /api/reports/priority/:eventId - Get priority reports

System Health

• GET /api/system-health - Get system health status

WebSocket Events

Client Subscribes To:

• map:update - Live map data updates
• alert:new - New alert notifications
• alert:updated - Alert status changes
• action:created - New emergency actions
• report:new - New incident reports
• insight:update - AI insight updates
• prediction:update - AI prediction updates

Client Emits:

• subscribe:zones - Subscribe to specific zones
• unsubscribe:zones - Unsubscribe from zones

Database Indexes

Geospatial Indexes

• location_pings.loc - 2dsphere index for location queries
• zones.polygon - 2dsphere index for zone queries
• events.bounds - 2dsphere index for event boundaries

TTL Indexes

• location_pings.createdAt - Expires after 900 seconds (15 minutes)

Query Optimization

• alerts.eventId + status - Alert filtering
• reports.eventId + status - Report filtering
• actions.eventId + createdAt - Action history
• users.email - Unique constraint and login

Authentication

JWT Tokens

• Access Token: 24-hour expiration, contains user ID, email, role
• Refresh Token: 7-day expiration, stored as httpOnly cookie
• Role-Based Access: admin, staff roles with hierarchical permissions

Protected Routes

• Most endpoints require valid JWT token in Authorization header
• Admin-only endpoints restricted to admin role
• Some report endpoints allow anonymous access

Real-time Features

Socket.IO Implementation

• Authentication: JWT token validation on connection
• Room Management: Automatic event and zone room joining
• Broadcasting: Targeted updates to specific events/zones
• Error Handling: Connection retry and error recovery

Live Data Streams

• Location Updates: Real-time crowd density visualization
• Alert Notifications: Instant emergency alert broadcasting
• Action Coordination: Live emergency response updates
• Report Notifications: Real-time incident report alerts

ML Service Integration

REST API Integration

• Insights Endpoint: POST to /insights with crowd data
• Predictions Endpoint: POST to /predictions with features
• Health Checks: Automatic ML service health monitoring
• Fallback Handling: Cached results when ML service unavailable

Data Flow

1. Backend aggregates location and zone data
2. Calls ML service with processed features
3. Caches ML results in MongoDB
4. Broadcasts updates via WebSocket
5. Serves cached data for subsequent requests

Emergency Notifications

Twilio Integration

• SMS Notifications: Emergency action and alert notifications
• WhatsApp Support: Rich media emergency notifications
• Bulk Messaging: Mass notification capabilities
• Delivery Tracking: Message status and error handling

Notification Triggers

• Critical Alerts: Automatic SMS/WhatsApp for critical severity
• Emergency Actions: Multi-channel delivery for emergency responses
• System Failures: Admin notifications for service degradation

Development

Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build TypeScript to JavaScript
• npm run start - Start production server
• npm run test - Run test suite
• npm run lint - Run ESLint
• npm run seed - Seed database with test data

Testing

• Unit Tests: Service layer testing with Jest
• Integration Tests: API endpoint testing with Supertest
• Socket Tests: WebSocket connection and event testing
• E2E Tests: Full workflow testing

Code Structure

src/
├── app.ts              # Express app configuration
├── server.ts           # Server startup and Socket.IO
├── config/             # Database, logging, environment
├── middleware/         # Authentication, error handling
├── models/             # Mongoose schemas and models
├── services/           # Business logic layer
├── controllers/        # Request/response handling
├── routes/             # API route definitions
└── utils/              # Helper functions and utilities

Deployment

Docker Support

# Build image
npm run docker:build

# Run container
npm run docker:run

Production Considerations

• Environment Variables: Secure JWT secrets and API keys
• Database: MongoDB Atlas or dedicated MongoDB instance
• SSL/TLS: HTTPS termination with reverse proxy
• Rate Limiting: API rate limiting and abuse prevention
• Monitoring: Health checks, logging, and alerting
• Scaling: Horizontal scaling with load balancer

Security

Authentication & Authorization

• JWT Tokens: Secure token-based authentication
• Role-Based Access: Hierarchical permission system
• Password Hashing: bcrypt with salt rounds
• Session Management: Secure cookie handling

API Security

• Helmet: Security headers and protection
• CORS: Cross-origin request configuration
• Rate Limiting: Request rate limiting per IP
• Input Validation: Zod schema validation
• SQL Injection: MongoDB query sanitization

Data Privacy

• PII Protection: Minimal personal data storage
• Audit Logging: Admin action logging
• Data Retention: TTL for ephemeral location data
• GDPR Compliance: Data deletion capabilities

Troubleshooting

Common Issues

1. MongoDB Connection:

   • Verify MONGO_URI is correct
   • Check MongoDB service is running
   • Ensure network connectivity

2. JWT Errors:

   • Verify JWT_SECRET is set and secure
   • Check token expiration
   • Validate token format

3. Socket.IO Issues:

   • Check CORS configuration
   • Verify frontend connection URL
   • Monitor connection logs

4. ML Service Integration:

   • Verify ML_BASE URL is accessible
   • Check ML service health endpoint
   • Monitor timeout configurations

Logs

• Application Logs: logs/combined.log
• Error Logs: logs/error.log
• Console Output: Real-time development logs

Health Monitoring

• Health Endpoint: /api/system-health
• Service Status: Database, ML service, Socket.IO
• Performance Metrics: Response times, error rates

License

MIT License - see LICENSE file for details.

Support

For technical support or questions about the CrowdShield AI backend:

• Create an issue in the project repository
• Contact the development team
• Review the API documentation and logs