Your AI-driven personal safety assistant combining geolocation, maps, AI (Gemini/OpenAI), and the MERN stack to make urban navigation safer and smarter.

Report Bug • Request Feature

Table of Contents

Details

Section	Section
Features	Quick Start
Use Cases	Frontend Contribution
Tech Stack	Contributing
System Architecture	Roadmap
Repository Structure	Contributors

Features

Feature	Description
JWT Authentication	Secure login & signup with bcrypt password hashing
Real-time Geolocation	Live location tracking with high accuracy
Nearby Safe Zones	Find hospitals, police stations, pharmacies instantly
AI Safety Assistant	Gemini/OpenAI powered safety recommendations
One-tap SOS	Emergency alerts with live location sharing
Safe Route Planning	AI-powered safest route recommendations
Cross-platform	Responsive design for all devices
Dark/Light Theme	Accessible interface with theme toggle

Use Cases

graph TD
    A[User Scenario] --> B[Walking Home Late]
    A --> C[Traveling in New City]
    A --> D[Emergency Situation]
    
    B --> E[Open SafePathAI App]
    C --> E
    D --> E
    
    E --> F[View Safe Routes & Zones]
    E --> G[Ask AI Assistant]
    E --> H[Hit SOS Button]
    
    F --> I[Get Safety Recommendations]
    G --> I
    H --> J[Send Emergency Alerts]
    
    I --> K[Reach Destination Safely]
    J --> K

Loading

Real-world Scenario:

Imagine you're walking home late at night. You open SafePathAI to:

• View nearby safe zones including hospitals and police stations
• Consult the AI assistant for the safest route recommendations
• Access instant SOS functionality that shares your live location with emergency contacts

The app provides peace of mind through real-time safety monitoring and intelligent route planning.

Tech Stack

Backend

Frontend (In Development)

AI & APIs

System Architecture

flowchart TD
    subgraph Frontend
        A[Next.js UI] --> B[Map Integration]
        A --> C[AI Chat Interface]
        A --> D[SOS Dashboard]
    end
    
    subgraph Backend
        E[Express Server] --> F[JWT Auth]
        E --> G[MongoDB]
        E --> H[AI Service]
        E --> I[Map APIs]
    end
    
    subgraph External Services
        J[Gemini/OpenAI] --> H
        K[Mapbox/Google Maps] --> I
        L[Emergency Services] --> M[SOS Alerts]
    end
    
    A <--> E
    F --> G
    H --> J
    I --> K

Loading

Repository Structure

SafePathAI/
├── 📂 backend/
│   ├── 📂 src/
│   │   ├── 📂 models/           # Database schemas
│   │   │   ├── User.ts          # User authentication model
│   │   │   ├── Place.ts         # Safe locations model
│   │   │   ├── SOS.ts           # Emergency alerts model
│   │   │   └── Chat.ts          # AI conversation history
│   │   ├── 📂 routes/           # API endpoints
│   │   │   ├── auth.ts          # Login/signup routes
│   │   │   ├── places.ts        # Location data routes
│   │   │   ├── ai.ts            # AI assistant routes
│   │   │   └── sos.ts           # Emergency alert routes
│   │   ├── 📂 controllers/      # Business logic
│   │   ├── 📂 middleware/       # Auth & error handling
│   │   └── index.ts             # Server entry point
│   ├── .env.example             # Environment template
│   ├── package.json
│   ├── package-lock.json
│   └── tsconfig.json
│
├── 📂 frontend/
│   ├── 📂 public/
│   │   ├── vite.svg
│   │   └── index.html
│   ├── 📂 src/
│   │   ├── 📂 components/
│   │   │   ├── 📂 Dashboard/
│   │   │   │   └── UserLocation.tsx
│   │   │   ├── Chat.tsx
│   │   │   ├── DarkModeToggle.tsx
│   │   │   ├── Footer.tsx
│   │   │   ├── Map.tsx
│   │   │   ├── Navbar.tsx
│   │   │   └── SOSButton.tsx
│   │   ├── 📂 context/
│   │   │   ├── AuthContext.tsx
│   │   │   └── ThemeContext.tsx
│   │   ├── 📂 pages/
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Emergency.tsx
│   │   │   ├── Favorites.tsx
│   │   │   ├── Login.tsx
│   │   │   └── Signup.tsx
│   │   ├── 📂 services/
│   │   │   ├── api.ts
│   │   │   └── (other service files)
│   │   ├── App.css
│   │   ├── App.tsx
│   │   ├── index.css
│   │   └── main.tsx
│   ├── .gitignore
│   ├── DESIGN_GUIDE.md
│   ├── README.md
│   ├── eslint.config.js
│   ├── package.json
│   ├── package-lock.json
│   ├── postcss.config.cjs
│   ├── postcss.config.js
│   ├── tailwind.config.js
│   ├── tsconfig.app.json
│   └── tsconfig.json
│
├── .gitignore
├── LICENSE.md
├── README.md
├── package.json
└── package-lock.json

Quick Start

Prerequisites

Installation

# 1. Clone the repository
git clone https://github.com/SrinjoyeeDey/SafePathAI-AI-Powered-Safety-Assistance-App.git
cd SafePathAI-AI-Powered-Safety-Assistance-App/backend

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your API keys

# 4. Start development server
npm run dev

# 5. Backend API running at:
# http://localhost:4000/api

graph LR
    A[Clone Repository] --> B[Install Dependencies]
    B --> C[Configure Environment]
    C --> D[Start Server]
    D --> E[API Ready!]

Loading

Environment Variables

Create .env file in /backend:

PORT=4000
MONGO_URI=your_mongodb_connection_string
JWT_ACCESS_SECRET=your_jwt_access_secret
JWT_REFRESH_SECRET=your_jwt_refresh_secret
OPENAI_API_KEY=your_openai_or_gemini_key
MAPBOX_API_KEY=your_mapbox_api_key

Frontend Contribution

Priority Tasks

• Mobile-responsive dashboard with Next.js + shadcn/ui
• Map integration with real-time location tracking
• AI chat interface with message history
• SOS emergency panel with one-tap functionality
• Theme system (green/white palette with dark/light mode)

Design Guidelines

Please follow our Design Guide for:

• Color Palette: Green/white theme with accessibility standards
• Typography: Consistent font hierarchy and spacing
• Components: Reusable UI patterns with shadcn/ui
• Responsive Layouts: Mobile-first approach

Good First Issues

Look for issues tagged with: good-first-issue frontend ui documentation

🤝 Contributing

We love your input! We want to make contributing as easy and transparent as possible.

Development Workflow

graph LR
    A[Fork Repository] --> B[Create Branch]
    B --> C[Make Changes]
    C --> D[Run Tests]
    D --> E[Submit PR]
    E --> F[Review & Merge]

Loading

Steps to Contribute

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

Development Guidelines

• Use TypeScript for all new code
• Follow React/Next.js best practices
• Use shadcn/ui components for consistency
• Write meaningful commit messages
• Test your changes thoroughly
• Update documentation if needed

Roadmap

Feature	Description
Core Backend	JWT Auth, MongoDB, Basic AI
Frontend Development	Next.js UI, Map Integration
Real-time Features	Live location sharing, notifications
Advanced AI	Predictive safety analytics
Mobile App	React Native application
Multi-language	Internationalization support
Offline Mode	Basic functionality without internet
Community Features	User reviews, safety tips

Contributors

🏆 Our Amazing Contributors

Why Contribute?

• Learn Real-world Skills: MERN stack + AI integration
• Showcase Talent: Build portfolio with modern technologies
• Make Impact: Create something that enhances personal safety
• Join Community: Collaborate with developers worldwide
• Recognition: Featured in contributors section & certificates

Get Involved

• Discussions: Share ideas in GitHub Discussions
• Issues: Report bugs or request features
• Documentation: Help improve docs and guides
• Code Reviews: Participate in peer reviews

---

Join Our Community

Star ⭐ this repo if you find it interesting!

Share with friends who might want to contribute to an impactful open-source project.

Built with ❤️ for the open-source community
Author: Srinjoyee Dey
Contributions welcome from everyone 🙌