CivicAlert 🚨

Real-Time Emergency Incident Reporting Platform

Empowering communities through instant incident reporting, intelligent routing, and coordinated emergency response systems.

Live Demo • Report Bug • Request Feature

📋 Table of Contents

Overview
Features
Tech Stack
Project Structure
Getting Started
Deployment
API Documentation
Screenshots
Contributing
License
Contact

🎯 Overview

CivicAlert is a comprehensive emergency incident reporting and management platform designed to bridge the gap between citizens and emergency services. It enables real-time incident reporting, verification, tracking, and resolution through an intuitive web interface with advanced mapping capabilities.

Why CivicAlert?

Instant Reporting: Report emergencies in seconds with photo, location, and voice notes
Real-Time Updates: Live incident tracking on interactive maps
Admin Verification: Multi-level verification system ensures accuracy before dispatch
Community Engagement: Foster civic participation through transparent incident resolution
Smart Notifications: Intelligent alert system notifies relevant responders and nearby citizens

✨ Features

🚨 Core Features

1. Real-Time Incident Reporting System

The platform provides a comprehensive incident reporting interface that makes emergency reporting quick, accurate, and accessible to everyone.

Multi-Format Media Upload
- 📸 Photo upload with drag-and-drop interface or click-to-browse
- 🎤 Voice note recording for hands-free reporting (up to 60 seconds)
- 📹 Video upload support for detailed incident documentation
- 🖼️ Image preview before submission with edit/delete options
- 📦 Multiple file upload support (up to 5 files per report)
- ⚡ Automatic image compression and optimization
Advanced Location Services
- 🗺️ Real-time GPS location tracking with high accuracy
- 🔍 Address autocomplete powered by OpenStreetMap
- 📍 Manual location picker with interactive map interface
- 🏠 Address verification and formatting
- 🌐 Reverse geocoding for automatic address detection
- 📱 Mobile device location permission handling
Smart Categorization
- 🔥 Fire Emergency: Building fires, forest fires, vehicle fires
- 🚑 Medical Emergency: Accidents, health emergencies, injuries
- 🚨 Crime: Theft, assault, suspicious activity
- 🏗️ Infrastructure Issue: Potholes, broken streetlights, damaged roads
- 🌊 Natural Disaster: Floods, earthquakes, storms
- 🚗 Road Accident: Vehicle collisions, traffic hazards
- ⚠️ Other: General safety concerns and civic issues
Severity Assessment
- 🔴 Critical: Immediate life-threatening situations requiring instant response
- 🟠 High: Urgent matters needing rapid attention
- 🟡 Medium: Important issues requiring timely resolution
- 🟢 Low: Non-urgent matters for routine handling
Detailed Incident Documentation
- ✍️ Rich text description with character count (up to 1000 characters)
- 🏷️ Optional custom tags and keywords
- 👤 Anonymous reporting option for sensitive situations
- 📅 Automatic timestamp and date logging
- 🔢 Unique incident ID generation for tracking

2. Interactive Mapping System

Advanced mapping capabilities provide real-time visualization and geographic analysis of incidents.

Dynamic Incident Visualization
- 🗺️ OpenStreetMap integration with Leaflet.js
- 📌 Color-coded markers based on severity levels
- 🎯 Click markers to view incident summaries
- 🔄 Auto-refresh every 30 seconds for live updates
- 📐 Distance calculation between user and incidents
- 🎨 Custom marker icons for different incident types
Map Interaction Features
- 🔍 Zoom controls (zoom in/out/reset)
- 🖱️ Pan and drag to explore areas
- 📍 Center map on user location
- 🎯 Search location by address or coordinates
- 📏 Measure distance tool
- 🌓 Toggle between map styles (street/satellite)
Filtering and Search
- 🔎 Filter by incident type, severity, status
- 📅 Date range filtering
- 📍 Radius-based search (1km, 5km, 10km, 20km)
- 🏷️ Tag-based filtering
- 💾 Save custom filter presets
Geographic Clustering
- 🎈 Automatic clustering for dense areas
- 🔢 Cluster count badges
- ⚡ Smooth zoom animations
- 📊 Heat map view option

3. Comprehensive Admin Dashboard

A powerful control center for managing incidents, users, and system operations.

Incident Management
- 📋 View all incidents in list or grid view
- 🔍 Advanced search and filtering system
- 📊 Sort by date, severity, status, location
- ✏️ Edit incident details inline
- 🗑️ Archive or delete inappropriate reports
- 📈 Bulk operations (verify multiple, update status)
- 🔄 Incident workflow automation
Verification System
- ✅ Multi-level verification workflow:
  - Step 1: Initial review for validity
  - Step 2: Cross-reference with other reports
  - Step 3: Contact verification (optional)
  - Step 4: Final approval
- 🤖 AI-powered duplicate detection
- 📸 Image authenticity verification
- 🔗 Link related incidents
- 📊 Credibility scoring system
- ⚠️ Flag suspicious reports
- 👥 Assign to specific admin teams
Status Tracking
- 📝 Reported: New incident submitted by user
- 🔍 Verified: Confirmed legitimate by admin
- ⚙️ In Progress: Emergency response in action
- ✅ Resolved: Issue successfully addressed
- ❌ Rejected: Invalid or duplicate report
- 📦 Archived: Historical record
Analytics Dashboard
- 📊 Real-time statistics and metrics
- 📈 Incident trends and patterns
- 🌍 Geographic heat maps
- ⏱️ Average response time tracking
- 👥 User engagement metrics
- 📉 Resolution rate over time
- 📅 Daily/weekly/monthly reports
- 📤 Export data to CSV/PDF
Admin Tools
- 🔧 System configuration settings
- 👥 User management and roles
- 🚫 Ban/suspend problematic users
- 📢 Send mass notifications
- 🗂️ Category management
- 🎨 Customize severity levels
- 📝 Incident templates

4. Communication & Messaging System

Real-time communication between citizens, admins, and emergency responders.

Incident-Specific Conversations
- 💬 Thread-based messaging per incident
- 👤 User-to-admin direct messaging
- 👥 Multi-party conversations for complex incidents
- 📎 Attach files and images to messages
- 🔗 Share incident links within conversations
- 📌 Pin important messages
Real-Time Features
- ⚡ Instant message delivery with WebSocket
- ✓ Read receipts and typing indicators
- 🔔 Push notifications for new messages
- 💾 Automatic message history
- 🔍 Search within conversations
- 📤 Message delivery status
Admin Communication Panel
- 📬 Unified inbox for all conversations
- 🔢 Unread message counters
- 🎯 Priority message flagging
- 📋 Conversation filtering by incident
- 🏷️ Tag conversations for organization
- 📊 Response time analytics
- 🤖 Quick response templates
User Messaging Dashboard
- 📱 Mobile-responsive message interface
- 🔄 Auto-refresh for new messages
- 📅 Message timestamp and history
- 🔔 Desktop and mobile notifications
- ✉️ Email notifications (optional)
- 📞 Request callback feature

5. Smart Notifications & Alert System

Intelligent notification system that keeps everyone informed in real-time.

User Notifications
- 🔔 Real-time push notifications
- 📧 Email alerts (configurable)
- 📱 SMS notifications (optional)
- 🌍 Location-based proximity alerts
- 📊 Notification preferences dashboard
- 🔕 Do not disturb mode
- ⏰ Schedule quiet hours
Alert Types
- 🚨 Emergency Alert: Critical incidents nearby
- ✅ Status Update: Incident status changes
- 💬 New Message: Admin response received
- ✓ Verification: Report verified
- 🏆 Achievement: Milestone reached
- 📢 Public Announcement: Community-wide alerts
- ⚠️ Warning: Weather or safety advisories
Public Emergency Alerts
- 📡 Broadcast to users within radius
- 🎯 Severity-based alert prioritization
- 🗺️ Map-based alert visualization
- ⏰ Automatic expiration
- 📢 Custom alert messages
- 🔊 Audio alert option
- 📞 Call-to-action buttons
Notification Management
- ✓ Mark as read/unread
- 🗑️ Delete or archive
- 🔍 Search notification history
- 📊 Notification statistics
- ⚙️ Granular notification settings
- 🎨 Priority color coding
- 📱 Mobile app integration ready

6. Advanced User Management

Comprehensive user profiles and account management system.

Authentication & Security
- 🔐 Firebase Authentication integration
- 📧 Email/password authentication
- 🔗 Social login (Google, Facebook, Twitter)
- 📱 Phone number verification
- 🔑 Two-factor authentication (2FA)
- 🔄 Password reset and recovery
- 🛡️ Account security monitoring
- 🚫 Brute force protection
Role-Based Access Control
- 👤 Citizen: Report and view incidents
- 🛡️ Admin: Verify and manage incidents
- 👑 Super Admin: Full system access
- 🔧 Moderator: Content moderation
- 📊 Analyst: Read-only access to analytics
- 🚨 Emergency Responder: Priority access
- 🏢 Department Head: Team management
Profile Management
- 👤 Personal information (name, email, phone)
- 📸 Profile photo upload and cropping
- 🏠 Default location settings
- 📍 Saved addresses (home, work)
- 🔔 Notification preferences
- 🌐 Language and region settings
- 🎨 Theme preferences (light/dark)
- 🔒 Privacy settings
Activity Tracking
- 📊 Incident submission history
- ✅ Resolved incidents count
- 💬 Message activity
- 🏆 Achievements and badges
- ⭐ Community reputation score
- 📈 Engagement metrics
- 📅 Account creation date
- 🔄 Last activity timestamp
User Statistics Dashboard
- 📈 Personal impact metrics
- 🎯 Reports by category breakdown
- 📉 Resolution success rate
- ⏱️ Average response time received
- 🏅 Achievement progress
- 👥 Community ranking
- 📅 Activity calendar
- 📊 Contribution graphs

📊 Analytics & Statistics

Comprehensive data visualization and reporting tools.

Personal Impact Dashboard
- 📈 Total incidents reported (lifetime)
- ✅ Verified reports percentage
- 🎯 Resolved incidents count
- ⚡ Active incidents tracking
- ⏱️ Average response time
- 👥 Community impact (people helped)
- 📅 Reports this month/week
- 🏆 Achievement milestones
Category Analysis
- 📊 Reports by category pie chart
- 📈 Trend analysis over time
- 🔥 Most reported issue types
- 📍 Category distribution by location
- 📉 Category resolution rates
- ⏱️ Average resolution time per category
Severity Breakdown
- 🔴 Critical incidents count
- 🟠 High priority reports
- 🟡 Medium severity issues
- 🟢 Low priority matters
- 📊 Severity distribution graph
- 📈 Severity trends
Monthly Trends
- 📅 6-month reporting trend chart
- 📊 Month-over-month comparison
- 📈 Growth rate analysis
- 🎯 Peak reporting days/times
- 📉 Seasonal patterns
Achievement System
- 🏆 Quick Reporter: 10+ verified reports
- 🛡️ Community Guardian: 15+ resolved incidents
- ⭐ Top Contributor: Monthly leader
- 🚀 Early Adopter: First 100 users
- 💎 Platinum Member: 50+ verified reports
- 🔥 Rapid Responder: Quick reporting streak
- 🌟 Civic Hero: 100+ total reports

🔒 Security & Privacy

Enterprise-grade security measures to protect user data and system integrity.

Data Protection
- 🔐 End-to-end encryption for sensitive data
- 🛡️ SSL/TLS for all communications
- 🔒 Secure password hashing (bcrypt)
- 💾 Encrypted database storage
- 🔑 API key authentication
- 🚫 SQL injection prevention
- 🛡️ XSS attack protection
- 🔐 CSRF token validation
Access Control
- 🔐 JWT-based authentication
- 👤 Session management
- ⏰ Automatic session timeout
- 🔒 Role-based permissions
- 📝 Audit logging
- 🚫 IP blacklisting
- ⚡ Rate limiting
Privacy Compliance
- 📜 GDPR compliant data handling
- 🔒 User data anonymization options
- 📋 Comprehensive privacy policy
- 📄 Clear terms of service
- 🗑️ Right to data deletion
- 📤 Data export functionality
- 🔍 Transparent data usage
- 👤 Anonymous reporting option
System Security
- 🔧 Regular security audits
- 🔄 Automatic security updates
- 🛡️ DDoS protection
- 🔍 Vulnerability scanning
- 📊 Security monitoring
- 🚨 Incident response plan
- 💾 Regular backups
- 🔄 Disaster recovery

🎨 User Experience Features

Thoughtful design elements that enhance usability and accessibility.

Responsive Design
- 📱 Mobile-first approach
- 💻 Desktop optimized layouts
- 📲 Tablet-friendly interface
- 🔄 Adaptive UI components
- ⚡ Fast page load times
- 🎨 Consistent design system
- 🖼️ Progressive image loading
Performance Optimization
- ⚡ Lazy loading for images
- 📦 Code splitting
- 🔄 Caching strategies
- 🚀 CDN integration
- 📈 Lighthouse score optimization
- 💨 Minimal bundle size
- ⚙️ Server-side rendering
Accessibility
- ♿ WCAG 2.1 AA compliant
- ⌨️ Keyboard navigation support
- 🔊 Screen reader compatibility
- 🎨 High contrast mode
- 📏 Adjustable text sizes
- 🎯 Focus indicators
- 🗣️ Voice command support (planned)
Internationalization
- 🌐 Multi-language support (planned)
- 🗺️ Locale-based formatting
- 📅 Regional date/time formats
- 💱 Currency localization
- 🌍 Timezone handling

🛠️ Tech Stack

Frontend

Framework: Next.js 16.1.1 (React 19.2.3)
Language: TypeScript 5.x
Styling: Tailwind CSS 4
UI Components: Custom components with Lucide React icons
Maps: Leaflet + React-Leaflet
Authentication: Firebase Auth
HTTP Client: Fetch API
Deployment: Vercel

Backend

Framework: NestJS (Node.js)
Language: TypeScript
Database: MongoDB with Mongoose ODM
Real-Time: Socket.IO for WebSocket connections
Authentication: JWT + Firebase Admin SDK
File Upload: Multer for multipart/form-data
Deployment: Render

Development Tools

Version Control: Git
Code Editor: VS Code recommended
Package Manager: npm
Linting: ESLint
API Testing: Postman/Thunder Client

📁 Project Structure

CivicAlert/
├── frontend/                    # Next.js Frontend Application
│   ├── app/                     # App Router (Next.js 13+)
│   │   ├── components/          # Reusable React components
│   │   │   ├── Navbar.tsx
│   │   │   ├── Footer.tsx
│   │   │   ├── Hero.tsx
│   │   │   ├── IncidentCard.tsx
│   │   │   ├── IncidentMap.tsx
│   │   │   ├── MapPreview.tsx
│   │   │   ├── LocationPicker.tsx
│   │   │   ├── AlertNotifications.tsx
│   │   │   ├── ProfileMenu.tsx
│   │   │   └── ...
│   │   ├── admin/               # Admin-only pages
│   │   │   ├── page.tsx         # Admin dashboard
│   │   │   ├── profile/
│   │   │   ├── communication/
│   │   │   └── public-alerts/
│   │   ├── dashboard/           # User dashboard
│   │   │   ├── page.tsx
│   │   │   ├── messages/
│   │   │   └── alerts/
│   │   ├── report/              # Incident reporting
│   │   │   └── page.tsx
│   │   ├── incidents/           # Public incidents view
│   │   │   └── page.tsx
│   │   ├── incident/            # Incident details
│   │   │   └── [id]/
│   │   ├── statistics/          # User statistics
│   │   │   └── page.tsx
│   │   ├── login/               # Authentication
│   │   │   └── page.tsx
│   │   ├── signup/
│   │   │   └── page.tsx
│   │   ├── profile/             # User profile
│   │   │   └── page.tsx
│   │   ├── privacy/             # Privacy policy
│   │   │   └── page.tsx
│   │   ├── terms/               # Terms of service
│   │   │   └── page.tsx
│   │   ├── layout.tsx           # Root layout
│   │   ├── page.tsx             # Landing page
│   │   └── globals.css          # Global styles
│   ├── lib/                     # Utility libraries
│   │   ├── AuthContext.tsx      # Authentication context
│   │   ├── authService.ts       # Auth helper functions
│   │   ├── firebase.ts          # Firebase configuration
│   │   └── config.ts            # API configuration
│   ├── public/                  # Static assets
│   ├── next.config.ts           # Next.js configuration
│   ├── tailwind.config.js       # Tailwind CSS configuration
│   ├── tsconfig.json            # TypeScript configuration
│   └── package.json             # Frontend dependencies
│
├── backend/                     # NestJS Backend Application
│   ├── src/
│   │   ├── incidents/           # Incident management module
│   │   │   ├── incidents.controller.ts
│   │   │   ├── incidents.service.ts
│   │   │   ├── incidents.module.ts
│   │   │   └── schemas/
│   │   │       └── incident.schema.ts
│   │   ├── alerts/              # Alert system module
│   │   │   ├── alerts.controller.ts
│   │   │   ├── alerts.service.ts
│   │   │   ├── alerts.module.ts
│   │   │   └── schemas/
│   │   ├── communication/       # Messaging module
│   │   │   ├── communication.controller.ts
│   │   │   ├── communication.service.ts
│   │   │   ├── communication.module.ts
│   │   │   └── schemas/
│   │   ├── profile/             # User profile module
│   │   │   ├── profile.controller.ts
│   │   │   ├── profile.service.ts
│   │   │   ├── profile.module.ts
│   │   │   └── schemas/
│   │   ├── auth/                # Authentication module
│   │   ├── app.module.ts        # Root module
│   │   └── main.ts              # Application entry point
│   ├── scripts/                 # Database setup scripts
│   │   └── setup-database.js
│   ├── nest-cli.json            # NestJS CLI configuration
│   ├── tsconfig.json            # TypeScript configuration
│   └── package.json             # Backend dependencies
│
├── README.md                    # Project documentation
└── .gitignore                   # Git ignore rules

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js >= 18.x
npm >= 9.x
MongoDB >= 6.x (local or Atlas)
Git
Firebase Account (for authentication)

Installation

Clone the repository

git clone https://github.com/yourusername/civicalert.git
cd civicalert/CivicAlert

Install Frontend Dependencies
```
cd frontend
npm install
```
Install Backend Dependencies
```
cd ../backend
npm install
```

Environment Variables

Frontend Environment Variables

Create a .env.local file in the frontend/ directory:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3001

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id

Backend Environment Variables

Create a .env file in the backend/ directory:

# Server Configuration
PORT=3001
NODE_ENV=development

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017/civicalert
# OR for MongoDB Atlas:
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/civicalert?retryWrites=true&w=majority

# Firebase Admin SDK
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_CLIENT_EMAIL=your_service_account@your_project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour_Private_Key\n-----END PRIVATE KEY-----\n"

# CORS Configuration
CORS_ORIGIN=http://localhost:3000

# JWT Configuration (Optional)
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=7d

# File Upload Configuration
MAX_FILE_SIZE=10485760  # 10MB in bytes
UPLOAD_PATH=./uploads

Running Locally

1. Start MongoDB

If using local MongoDB:

# macOS/Linux
mongod

# Windows
"C:\Program Files\MongoDB\Server\6.0\bin\mongod.exe"

Or use MongoDB Atlas (cloud database).

2. Start Backend Server

cd backend
npm run start:dev

Backend will be available at: http://localhost:3001

3. Start Frontend Development Server

cd frontend
npm run dev

Frontend will be available at: http://localhost:3000

4. Setup Database (Optional)

Initialize database collections and indexes:

cd backend
node scripts/setup-database.js

🌐 Deployment

Frontend Deployment (Vercel)

Push to GitHub

git add .
git commit -m "Deploy to production"
git push origin main

Connect to Vercel
- Go to vercel.com
- Import your GitHub repository
- Select the frontend directory as root
- Configure environment variables (same as .env.local)
Deploy
- Click "Deploy"
- Vercel will automatically build and deploy
- Your site will be live at: https://your-project.vercel.app

Backend Deployment (Render)

Create Render Account
- Sign up at render.com
Create New Web Service
- Connect your GitHub repository
- Select the backend directory
- Set build command: npm install && npm run build
- Set start command: npm run start:prod
Configure Environment Variables
- Add all backend environment variables
- Update MONGODB_URI to your production database
- Update CORS_ORIGIN to your Vercel URL
Deploy
- Render will build and deploy automatically
- Your API will be live at: https://your-backend.onrender.com
Update Frontend API URL
- In Vercel, update NEXT_PUBLIC_API_URL to your Render backend URL
- Redeploy frontend

📡 API Documentation

Base URL

Local: http://localhost:3001
Production: https://civicalert-fm6x.onrender.com

Incidents Endpoints

Method	Endpoint	Description	Auth Required
GET	`/incidents`	Get all incidents	No
GET	`/incidents/:id`	Get incident by ID	No
POST	`/incidents`	Create new incident	Yes
PATCH	`/incidents/:id`	Update incident	Yes (Admin)
DELETE	`/incidents/:id`	Delete incident	Yes (Admin)
POST	`/incidents/:id/check-duplicates`	Check for duplicate incidents	Yes (Admin)

Alerts Endpoints

Method	Endpoint	Description	Auth Required
GET	`/alerts/user/:userId`	Get user alerts	Yes
GET	`/alerts/user/:userId/unread-count`	Get unread count	Yes
PATCH	`/alerts/:id/read`	Mark alert as read	Yes
POST	`/alerts/public`	Create public alert	Yes (Admin)

Profile Endpoints

Method	Endpoint	Description	Auth Required
GET	`/profile/user/:userId`	Get user profile	Yes
GET	`/profile/admin/:userId`	Get admin profile	Yes (Admin)
PATCH	`/profile/user/:userId`	Update user profile	Yes
PATCH	`/profile/admin/:userId`	Update admin profile	Yes (Admin)

Communication Endpoints

Method	Endpoint	Description	Auth Required
GET	`/communication/messages/:incidentId`	Get incident messages	Yes
POST	`/communication/messages`	Send message	Yes
PATCH	`/communication/messages/:id/read`	Mark message as read	Yes

Example Request

Create Incident

curl -X POST http://localhost:3001/incidents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "type": "Fire",
    "description": "Building fire at Main Street",
    "severity": "CRITICAL",
    "location": {
      "latitude": 40.7128,
      "longitude": -74.0060,
      "address": "123 Main St, New York, NY"
    }
  }'

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the Project
Create your Feature Branch
```
git checkout -b feature/AmazingFeature
```
Commit your Changes
```
git commit -m 'Add some AmazingFeature'
```
Push to the Branch
```
git push origin feature/AmazingFeature
```
Open a Pull Request

Coding Guidelines

Follow TypeScript best practices
Use meaningful variable and function names
Write clean, readable code with comments
Test your changes thoroughly
Update documentation as needed

Reporting Bugs

If you find a bug, please open an issue with:

Clear bug description
Steps to reproduce
Expected vs actual behavior
Screenshots if applicable
Environment details (OS, browser, versions)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Next.js - React Framework
NestJS - Backend Framework
MongoDB - Database
Firebase - Authentication
Leaflet - Interactive Maps
Tailwind CSS - Styling
Vercel - Frontend Hosting
Render - Backend Hosting
Lucide Icons - Icon Library

🗺️ Roadmap

Made with ❤️ for safer communities

⭐ Star this repo if you find it useful!

FilesExpand file tree

README.md

Latest commit

History