SOS – Emergency Alert & Live Location Tracker

Real-time emergency broadcast system with high-precision GPS tracking, multi-contact email dispatch, and Firebase Cloud Messaging

---

In critical emergency situations, responders and family members need immediate, unambiguous intelligence regarding an individual's whereabouts and safety status. This platform solves that challenge by delivering a single-tap emergency alert dashboard engineered for modern web and mobile browsers. Upon triggering an alert, the application continuously samples and refines GPS coordinates to achieve tight accuracy margins (±X meters), sounds an on-device siren alarm, and simultaneously broadcasts rich HTML notifications via Nodemailer (Gmail SMTP) and real-time Web Push alerts through Firebase Cloud Messaging (FCM) to all designated emergency contacts.

---

• One-Click Emergency Trigger & Audio Siren: Single-tap SOS activation featuring visual confirmation safety gates and integrated Web Audio API siren synthesis.
• Continuous GPS Accuracy Refinement: Native watchPosition geolocation sampling streaming coordinate updates over a precision window to select the smallest margin of error.
• Automated Multi-Contact Email Broadcasts: Dispatches structured, responsive HTML alert emails via Nodemailer detailing sender identity, latitude/longitude, accuracy radius, and direct Google Maps pin drops.
• Firebase Web Push Notifications (FCM): Dedicated receiver portal (/receive) allowing responders to register browser push tokens to receive background alerts even when their browser tab is inactive.
• Multi-Tab Dashboard & Audit Logging: Single-page navigation across Live Overview, Contact Directory, Firestore-backed Alert Logs, and Preference Settings.
• One-Click Diagnostic Testing: On-demand SMTP test trigger in the Settings panel to verify email transport and credentials without firing an active emergency alert.

---

Layer	Technology
Backend Framework	Node.js, Express.js
Email Dispatch Engine	Nodemailer (Gmail SMTP Transport)
Cloud Database & Web Push	Firebase Admin SDK (Cloud Firestore, Firebase Cloud Messaging / FCM)
Frontend Client	HTML5, CSS3 (Glassmorphic Cyberpunk UI, CSS Keyframe Animations), Vanilla JavaScript (ES6 Modules)
Device APIs	Browser Geolocation API (watchPosition), Web Audio API, Service Worker API (firebase-messaging-sw.js)
Environment & Telecom	Dotenv, CORS, Twilio SDK (Optional)

---

flowchart TD
    subgraph Client ["Sender Console (index.html / script.js)"]
        A["User Taps SOS Button"] --> B{"Confirmation Safety Gate"}
        B -- Confirm --> C["Web Geolocation API (watchPosition)"]
        B -- Confirm --> D["Web Audio API (Synthesize Siren)"]
        C --> E["Refine Accuracy (Lowest Margin)"]
        E --> F["POST /api/sos (Payload)"]
    end

    subgraph Backend ["Express Application Server (server.js)"]
        F --> G["Express Router (/api/sos)"]
        G --> H1["Query Contacts (Cloud Firestore)"]
        G --> H2["Nodemailer (Gmail SMTP Broadcast)"]
        G --> H3["Firebase Admin SDK (FCM Multicast)"]
        G --> H4["Append Audit Log (Firestore)"]
    end

    subgraph Delivery ["Responder Reception Channels"]
        H2 --> I["Email Inboxes (HTML Alert + Google Maps Pin)"]
        H3 --> J["Receiver Browser (/receive / Service Worker)"]
        H4 --> K["Dashboard Audit History (/logs)"]
    end

Loading

---

Prerequisites

• Node.js (v14.0.0 or higher)
• npm (Node Package Manager)
• Gmail account with an App Password generated
• Firebase project with Cloud Firestore and Firebase Cloud Messaging enabled

1. Clone the Repository

git clone https://github.com/tejas-coder28/SOS-EmergencyApp.git
cd SOS-EmergencyApp

2. Install Dependencies

npm install

3. Configure Environment Variables

Copy the template configuration file:

cp .env.example .env

Edit .env and insert your credentials:

EMAIL_USER="your_email@gmail.com"
EMAIL_PASS="your_16_char_app_password"
ALERT_USER_NAME="Your Name"
PORT="3000"
NODE_ENV="development"
GOOGLE_APPLICATION_CREDENTIALS="./firebase-service-account.json"
FIREBASE_PROJECT_ID="your_project_id"
FIREBASE_API_KEY="your_api_key"
FIREBASE_AUTH_DOMAIN="your_auth_domain.firebaseapp.com"
FIREBASE_STORAGE_BUCKET="your_storage_bucket.appspot.com"
FIREBASE_MESSAGING_SENDER_ID="your_messaging_sender_id"
FIREBASE_APP_ID="your_app_id"
FIREBASE_VAPID_KEY="your_web_push_vapid_key"

4. Start the Application

# Production start
npm start

# Development mode with auto-reload (requires nodemon)
npm run dev

5. Access the Interfaces

• Sender Console: http://localhost:3000/index.html
• Receiver Opt-in Portal: http://localhost:3000/receive.html

---

SOS-EmergencyApp/
├── docs/
│   └── assets/                   # Architecture charts & UI screenshots
├── public/
│   └── firebase-config.js        # Client Firebase configuration loader
├── firebase-messaging-sw.js      # Service Worker handling background Web Push notifications
├── index.html                    # Main emergency dispatch console interface
├── receive.html                  # Receiver opt-in & background notification registration
├── receive.js                    # Receiver client logic & FCM token handling
├── script.js                     # Main client logic, GPS refinement & audio synthesis
├── server.js                     # Express server, Nodemailer transport & Firebase Admin routes
├── style.css                     # Tactical glassmorphic cyberpunk stylesheet & animations
├── package.json                  # Dependencies and npm execution scripts
├── package-lock.json             # Locked dependency tree
├── .env.example                  # Environment configuration template
├── .gitignore                    # Git untracked ignore rules
├── LICENSE                       # MIT License
└── README.md                     # Project documentation

---

1. Emergency Dispatch Interface

High-visibility dispatch console featuring the central SOS trigger button and live accuracy indicator.

TODO: Capture screenshot of the main dashboard UI at http://localhost:3000/index.html and save to /docs/assets/01_emergency_sos_dashboard.png.

2. Contact Management Directory

Add and manage emergency contact emails stored securely in Cloud Firestore.

TODO: Capture screenshot of the Contacts Directory tab and save to /docs/assets/02_contact_directory_modal.png.

3. Receiver Opt-in Portal

Public receiver endpoint for responders to register browser push notifications.

TODO: Capture screenshot of http://localhost:3000/receive.html and save to /docs/assets/03_receiver_push_portal.png.

4. Real-Time Alert Audit Logs

Historical audit table capturing activation timestamps, coordinates, and dispatch confirmations.

TODO: Capture screenshot of the Alert Logs tab and save to /docs/assets/04_audit_history_logs.png.

---

• Live WebSocket Coordinate Streaming: Stream moving GPS coordinate breadcrumbs in real time on an interactive Leaflet / Mapbox map.
• Automated SMS Telecom Fallback: Cascade failed email dispatches directly to carrier SMS via Twilio or AWS SNS.
• Progressive Web App (PWA) Offline Manifest: Full PWA caching enabling instant homescreen launch on Android and iOS devices.

---

Tejas Muralidhar

• GitHub: @tejas-coder28
• LinkedIn: Tejas Muralidhar