SafeTraiL is a premium, real-time emergency response platform designed to bridge the gap between victims, their personal guardians, and professional emergency services. With high-fidelity maps, real-time location tracking, and automated alerting, SafeTraiL ensures that help is never more than a heartbeat away.
- Framework: React.js with Vite
- State Management: Zustand (Auth, SOS, Socket, UI states)
- Data Fetching: TanStack Query (React Query)
- Styling: Tailwind CSS + Framer Motion (Animations)
- Mapping: Leaflet + React-Leaflet (OpenStreetMap)
- Real-time: Socket.io-client
- Runtime: Node.js
- Framework: Express.js
- Real-time Engine: Socket.io
- Database: PostgreSQL with PostGIS extension via Supabase (Spatial queries)
- Task Queue: BullMQ + Redis via Upstash (Async SMS/Push alerts)
- Validation: Zod
- Frontend: Vercel
- Backend API: Render (Node.js Web Service)
- Database: Supabase — Free-tier managed PostgreSQL + PostGIS
- Cache & Queues: Upstash — Free-tier serverless Redis (TLS)
- Nominatim: Reverse geocoding (Coordinates to Addresses)
- OpenStreetMap Overpass: Sourcing nearby emergency infrastructure (Hospitals, Police, Pharmacies)
- OSRM Engine: Real-time routing and ETA calculations
- SMS Gateway: Twilio / Generic SMS API support
SafeTraiL/
├── client/ # React Frontend (Vite)
│ ├── src/
│ │ ├── api/ # API Service Layer
│ │ ├── components/ # UI, SOS, Layout components
│ │ ├── hooks/ # Geolocation, Socket hooks
│ │ ├── pages/ # Auth, Dashboard, Map, SOS Active
│ │ └── store/ # Zustand state management
├── server/ # Node.js Backend
│ ├── src/
│ │ ├── controllers/ # Request handlers
│ │ ├── db/ # PostgreSQL queries & migrations
│ │ ├── jobs/ # BullMQ workers (Alerting, Processing)
│ │ ├── routes/ # API Endpoint definitions
│ │ ├── services/ # Domain logic (SOS, Maps, Auth)
│ │ └── sockets/ # Real-time event handlers
├── assets/ # Project documentation images
├── supabase_schema.sql # Unified DB schema for Supabase SQL Editor
├── render.yaml # Render deployment configuration
└── docker-compose.yml # Local development environment- SOS Emergency Trigger: A dedicated high-stakes trigger with configurable hold duration (1s, 2s) to prevent accidental activation.
- Real-time Guardian Alerts: Instant SMS and Socket.io notifications sent to your personal "Guardian Circle".
- Live Victim Tracking: Guardians can track the victim's movement on a live map with sub-second updates.
- Nearby Emergency Help: Automatic detection of the nearest Hospital and Police Station (searches up to 50km).
- Interactive Incident Map: Community-driven safety reports on a visual heatmap.
- Smart Routing: One-tap navigation from the victim's location to the nearest help point with live ETAs.
- Personalized Dashboard: A responsive, desktop-friendly console showing active SOS status and safety stats.
SafeTraiL follows a Distributed Event-Driven Architecture. Real-time location streams are handled via Socket.io for immediate UI updates, while mission-critical alerts are processed through persistent Redis queues to ensure reliability even under heavy load.
POST /register- Create a new user/volunteer account.POST /login- Authenticate and receive JWT tokens.POST /refresh- Rotate expired access tokens.POST /logout- Invalidate current session.
GET /me- Fetch current user profile.PATCH /me- Update user profile.PATCH /me/location- Update background location.
POST /trigger- Initiate an SOS event (pings guardians + queues alerts).POST /:eventId/location- Victim-side location pings.GET /:eventId/location- Fetch latest victim position.GET /:eventId- Fetch specific SOS event details (victim info, etc.).PATCH /:eventId/resolve- Mark emergency as handled.GET /history- View personal SOS alert history.
GET /- List current guardian circle.GET /invites- List pending invitations.POST /- Invite a new guardian by phone/email.DELETE /:guardianId- Remove a guardian from circle.PATCH /:circleId/accept- Accept a guardian invitation.
GET /nearby- Search for infrastructure within radius (OSM Overpass API).GET /nearest- Find the single absolute closest emergency point.GET /route- Calculate paths and ETAs via OSRM.GET /geocode/reverse- Resolve coordinates to street address.GET /live/:sosEventId- Fetch full live GeoJSON tracking trail.GET /heatmap- Fetch geographic heatmaps for analytics.
POST /- Submit a new safety report.GET /nearby- Fetch reports within visual range.GET /:id- Fetch single incident details.
POST /:sosEventId/chunk- Upload encrypted live audio chunk during active SOS.GET /:sosEventId/chunk/:chunkId- Stream a specific audio chunk securely.GET /:sosEventId- List all audio chunks collected for an SOS event.DELETE /:sosEventId- Purge evidence securely (Owner/Admin).
GET /settings- Fetch voice activation settings.PUT /settings- Update voice activation preferences.GET /keywords- List registered voice trigger keywords.POST /keywords- Add a custom voice keyword trigger.DELETE /keywords/:id- Remove a custom keyword.POST /trigger- Direct SOS trigger via background keyword match.
GET /stats- Fetch overall system statistics.GET /heatmap- Get localized cluster density data.GET /sos/active- List currently active network-wide SOS events.PATCH /users/:id/role- Elevate or revoke administrative rights.
- Node.js (v20+)
- A Supabase project (free tier) with PostGIS enabled
- An Upstash Redis instance (free tier)
- Twilio Account (for SMS alerts)
- Create a free project at supabase.com.
- Go to SQL Editor → New Query.
- Copy the contents of
supabase_schema.sqland run it. - Go to Table Editor to confirm all tables were created.
- Copy your Session mode connection string from Project Settings → Database.
- Create a free Redis database at upstash.com.
- Copy the Redis URL (starts with
rediss://).
Create a server/.env file. Use server/.env.example as a template:
NODE_ENV=development
PORT=3001
# Supabase PostgreSQL
DATABASE_URL=postgresql://postgres.<project-ref>:<password>@aws-X.pooler.supabase.com:5432/postgres
# Upstash Redis (TLS)
REDIS_URL=rediss://default:<password>@<host>.upstash.io:6379
# JWT Secrets (generate strong random strings, min 32 chars)
ACCESS_TOKEN_SECRET=your_access_token_secret_here
REFRESH_TOKEN_SECRET=your_refresh_token_secret_here
ACCESS_TOKEN_EXPIRES_IN=15m
REFRESH_TOKEN_EXPIRES_IN=7d
# Twilio (optional — SMS alerts skipped if not set)
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=+1xxxxxxxxxx
# Firebase Admin SDK (optional — push notifications skipped if not set)
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
FIREBASE_CLIENT_EMAIL=firebase-adminsdk@your-project.iam.gserviceaccount.comBoth the database and Redis are cloud-hosted. The local Docker setup only runs the backend API and client:
docker compose up --buildThe application will be accessible at http://localhost:5173.
Backend:
cd server
npm install
npm run devFrontend:
cd client
npm install
npm run dev| Service | Platform | Notes |
|---|---|---|
| Frontend | Vercel | Auto-deploys on push to main |
| Backend API | Render | Configured via render.yaml |
| Database | Supabase | Free-tier PostgreSQL + PostGIS |
| Cache & Queues | Upstash | Free-tier serverless Redis (TLS) |
The render.yaml file defines the backend web service. Set the following environment variables in the Render dashboard under your web service → Environment:
DATABASE_URL— Your Supabase session-mode connection stringREDIS_URL— Your Upstash Redis URL (rediss://...)ACCESS_TOKEN_SECRET,REFRESH_TOKEN_SECRETTWILIO_*andFIREBASE_*credentials
