🚨 SOS Emergency Alert App

An Android emergency alert application that automatically captures evidence and sends alerts to emergency contacts with real-time location tracking.

📱 Features

• 🔒 Dual Password System: Dashboard access and emergency trigger via gallery password
• 📸 Automatic Evidence Capture: rear camera photos + 5-second video
• 📍 Real-time Location Tracking: GPS coordinates with accuracy information
• 💬 SMS Alerts: Instant notifications to emergency contacts via Twilio
• 🌐 Web Dashboard: Emergency contacts receive a web link to view all information
• ☁️ Cloud Backup: All data securely stored in Firebase
• 🎭 Decoy Gallery: Secret gallery access for emergency mode

🏗️ Technology Stack

Android App

• Kotlin - Primary programming language
• Jetpack Compose - Modern UI framework
• Room Database - Local data persistence
• CameraX - Camera functionality
• WorkManager - Background task scheduling

Backend Services

• Firebase Firestore - Real-time database
• Firebase Storage - Media file storage
• Firebase Functions - Serverless cloud functions
• Firebase Hosting - Web dashboard hosting

Third-Party Services

• Twilio - SMS notification service

🚀 Getting Started

Prerequisites

1. Android Studio (Arctic Fox or newer)
2. Firebase Account - Create one here
3. Twilio Account - Sign up here
4. Firebase CLI - Install via npm install -g firebase-tools

⚠️ Important: Credentials Setup

This repository contains placeholder credentials for security. Before running the app, you MUST set up your own credentials.

📖 See detailed setup instructions in: CREDENTIALS_SETUP.md

Quick Setup Overview

1. Firebase Setup

   • Create a Firebase project
   • Download google-services.json and replace in app/
   • Update Firebase config in public/index.html

2. Twilio Setup

   • Get Twilio credentials from console
   • Update credentials in functions/index.js

3. Android SDK

   • Delete local.properties (will be auto-generated)
   • Open project in Android Studio

For complete step-by-step instructions, see CREDENTIALS_SETUP.md.

📦 Installation

1. Clone the Repository

git clone https://github.com/YOUR_USERNAME/SOS_PROJECT.git
cd SOS_PROJECT

2. Set Up Credentials

Follow the complete guide in CREDENTIALS_SETUP.md

3. Install Dependencies

# Firebase Functions dependencies
cd functions
npm install
cd ..

4. Open in Android Studio

• Open Android Studio
• Select "Open an Existing Project"
• Navigate to the cloned repository
• Wait for Gradle sync to complete

🎯 How It Works

Normal Mode

1. User opens app and enters dashboard password
2. Access to settings, emergency contacts, and app configuration
3. Can test emergency features safely

Emergency Mode

1. User opens gallery app and enters emergency (gallery) password
2. App automatically activates emergency mode in background:
   • 📸 Captures 2 photos (front + rear camera)
   • 🎥 Records 5-second video
   • 📍 Gets precise GPS location
   • ☁️ Uploads all data to Firebase
   • 💬 Sends SMS alerts with web link to all emergency contacts
3. Emergency contacts receive SMS with link to web dashboard
4. Web dashboard displays location, photos, video, and incident details

📱 App Structure

app/
├── src/main/java/com/example/sosapp/
│   ├── data/              # Data layer
│   │   ├── firebase/      # Firebase integration
│   │   ├── local/         # Room database
│   │   └── repository/    # Data repositories
│   ├── ui/                # UI layer (Jetpack Compose)
│   │   ├── auth/          # Password screens
│   │   ├── dashboard/     # Main dashboard
│   │   ├── gallery/       # Decoy gallery
│   │   └── setup/         # Initial setup
│   ├── services/          # Background services
│   ├── workers/           # WorkManager tasks
│   └── utils/             # Utility classes
├── google-services.json   # Firebase config (needs setup)
└── build.gradle.kts       # Dependencies

functions/
├── index.js              # Cloud Functions (needs Twilio setup)
└── package.json          # Node dependencies

public/
└── index.html            # Emergency web dashboard (needs Firebase config)

🔧 Configuration Files

File	Purpose	Setup Required
app/google-services.json	Firebase Android config	✅ Yes
public/index.html	Firebase web config	✅ Yes
functions/index.js	Twilio credentials	✅ Yes
local.properties	Android SDK path	Auto-generated

🌐 Deployment

Deploy Firebase Functions & Hosting

# Login to Firebase
firebase login

# Deploy everything
firebase deploy

Deploy only Functions

firebase deploy --only functions

Deploy only Hosting

firebase deploy --only hosting

🧪 Testing

Test Twilio Integration

curl "https://YOUR-PROJECT.cloudfunctions.net/testTwilio?phone=+1234567890"

Test Emergency Alert

1. Open app in Android Studio
2. Enter setup credentials
3. Add test emergency contacts
4. Trigger emergency mode via gallery password
5. Check Firebase Console for uploaded data
6. Verify SMS received by contacts

🔒 Security Features

• ✅ All credentials sanitized for public repository
• ✅ Dual password system for security
• ✅ Encrypted password storage (BCrypt hashing)
• ✅ Secure cloud storage (Firebase)
• ✅ HTTPS communication
• ✅ .gitignore configured to prevent credential leaks

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Note: Never commit real credentials in pull requests!

📝 License

This project is for educational purposes. Please use responsibly and in accordance with local laws regarding emergency services and personal safety applications.

⚠️ Disclaimer

This app is designed for emergency situations. Always contact local emergency services (911, 112, etc.) for immediate help. This app supplements but does not replace official emergency services.

🐛 Known Issues

• Camera permissions required for evidence capture
• Location permissions required for GPS tracking
• Background service may be restricted on some devices (battery optimization)
• SMS delivery depends on Twilio account status and recipient network

📞 Support

For setup issues, please refer to:

1. CREDENTIALS_SETUP.md - Setup instructions
2. Firebase Documentation
3. Twilio Documentation

🎓 Author

• Built with ❤️ for emergency safety

🔄 Version History

• v1.0.0 - Initial release
  • Dual password system
  • Automatic evidence capture
  • SMS alerts via Twilio
  • Web dashboard
  • Cloud backup

---

⭐ If this project helped you, please consider giving it a star!

🔐 Remember to set up your credentials before running! See CREDENTIALS_SETUP.md