Avaya — Women's Safety Navigation

Because the safest path and the shortest path are two very different things.

---

🌸 The Problem

Every day, millions of women make a decision that most people never think about — "Is this route safe enough?"

Traditional maps like Google Maps optimize for speed and distance. They don't know which street is poorly lit. They don't know which lane has a history of incidents. They don't factor in whether a route has CCTV coverage or is near a police station.

Avaya was built to change that.

We show you the safest route, not just the shortest one — scored dynamically using real-world safety factors, adjusted in real-time based on the time of day.

---

✨ Key Features

🗺️ Safety-Scored Routing

Every road segment on the map is scored and color-coded based on real factors:

Factor	How It's Used
💡 Street Lighting	Lit roads boost the safety score
📹 CCTV Presence	Surveilled areas score higher
👥 Crowd Density	High-traffic areas feel safer
🚔 Police Proximity	Closer to a station = higher score
📊 Incident History	Past reports lower the score
🌙 Time of Day	Scores dynamically adjust at night

Routes are presented side-by-side — so you can compare the safest path vs. the shortest path and make an informed choice.

---

🚨 One-Tap SOS Emergency

When every second counts, Avaya's SOS button does everything at once:

┌─────────────────────────────────────────────────┐
│  👆 ONE TAP                                     │
│                                                 │
│  → 📍 Pins your exact live location on the map  │
│  → 🚔 Sends location to nearest police station  │
│  → 📢 Posts an alert to the community feed      │
│                                                 │
│  No typing. No searching. Just one tap.         │
└─────────────────────────────────────────────────┘

---

🤝 Community Feed

A built-in social safety network where users can:

• 📝 Share safety tips and local advisories
• ⚠️ Report incidents to warn others in real-time
• 🚨 See SOS alerts from nearby users with live location
• 💬 Comment and support each other
• ❤️ Like posts to surface the most important ones

---

🔐 Secure Authentication

Powered by Clerk, Avaya supports:

• Email/password sign-up & sign-in
• Social login (Google, GitHub, etc.)
• Protected routes — map & community require authentication
• User avatars and profile management

---

🏗️ Architecture

avaya/
├── client/                    # React Frontend
│   ├── src/
│   │   ├── components/
│   │   │   ├── Map/           # AvayaMap, RoadLayer, UserMarker, DestinationMarker
│   │   │   ├── UI/            # SOSButton, SOSModal, SearchBar, RoutePanel,
│   │   │   │                  # RouteSelectorPanel, SafetyLegend, Toast, etc.
│   │   │   └── Layout/        # SiteHeader, SiteFooter, SiteLayout, AuthLayout
│   │   ├── pages/             # Landing, Map, SignIn, SignUp, About, Contact,
│   │   │                      # HowItWorks, SafetyTips, NotFound
│   │   ├── services/          # API client (Axios)
│   │   ├── store/             # Zustand state management
│   │   ├── hooks/             # Custom React hooks
│   │   └── main.jsx           # App entry with Clerk provider
│   └── package.json
│
├── backend/                   # Node.js API Server
│   ├── src/
│   │   ├── routes/
│   │   │   ├── roads.js       # Safe routing engine + road segments API
│   │   │   └── police.js      # Nearest police station lookup
│   │   ├── db/
│   │   │   └── index.js       # PostgreSQL + PostGIS schema, triggers, views
│   │   └── middleware/
│   │       └── errorHandler.js
│   ├── server.js              # Express entry point
│   └── package.json
│
└── README.md

---

🛠️ Tech Stack

Frontend

Technology	Purpose
React 19	UI framework with latest concurrent features
Vite 7	Lightning-fast dev server and build tool
Tailwind CSS 4	Utility-first styling
Leaflet + React-Leaflet	Interactive safety maps with custom layers
Clerk	Authentication, user management, and protected routes
Zustand	Lightweight state management
Axios	HTTP client for API communication
Lucide React	Beautiful, consistent iconography
React Router DOM 7	Client-side routing and navigation

Backend

Technology	Purpose
Node.js	Server runtime
Express 5	Web framework for API routes
PostgreSQL	Relational database
PostGIS	Spatial queries — distance, geometry, geolocation
pgRouting	Graph-based shortest/safest path computation
NeonDB	Serverless PostgreSQL hosting
Graphology	In-memory graph processing for route optimization
dotenv	Environment variable management

---

🧮 How the Safety Score Works

Avaya computes a dynamic safety score (0–10) for every road segment using a custom SQL view:

Final Score = Base Safety Score
              + Lighting Bonus         (+1.0 if lit)
              + CCTV Bonus             (+1.0 if present)
              + Crowd Level Bonus      (+1.0 high / -1.0 low)
              + Police Proximity Bonus (up to +2.0 based on distance)
              - Incident Penalty       (up to -3.0 based on reports)
              × Night Modifier         (×0.7 between 10 PM – 5 AM)

This score is recalculated in real-time so the same road may be rated differently at noon versus midnight.

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 18
• PostgreSQL with PostGIS & pgRouting extensions (or a NeonDB account)
• Clerk account for authentication (clerk.com)

1. Clone the repository

git clone https://github.com/your-username/avaya.git
cd avaya

2. Backend Setup

cd backend
npm install

Create a .env file:

NODE_ENV=development
DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require
PORT=5000

Start the dev server:

npm run dev

Verify it's working:

GET http://localhost:5000/health
→ { "status": "ok", "db": "connected" }

3. Frontend Setup

cd client
npm install

Create a .env file:

VITE_API_BASE_URL=http://localhost:5000
VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_clerk_key

Start the dev server:

npm run dev

Visit http://localhost:5173 🎉

---

📡 API Endpoints

Roads & Routing

Method	Endpoint	Description
GET	/api/roads/segments	Get all road segments with safety scores
GET	/api/roads/route	Compute safest route between two points

Police Stations

Method	Endpoint	Description
GET	/api/police/nearest?lat=&lng=	Find nearest active police station

Community

Method	Endpoint	Description
GET	/api/community/posts	Paginated community feed with filters
POST	/api/community/posts	Create a new post
GET	/api/community/posts/:id	Get post details with comments
POST	/api/community/posts/:id/comments	Add a comment
POST	/api/community/posts/:id/like	Toggle like on a post
POST	/api/community/sos-alert	Trigger an SOS community alert

Health

Method	Endpoint	Description
GET	/health	Server + database health check

---

🗃️ Database Schema

┌──────────────────┐     ┌──────────────────────┐     ┌────────────────┐
│  police_stations │     │    road_segments      │     │     users      │
├──────────────────┤     ├──────────────────────┤     ├────────────────┤
│ id               │◄────│ nearest_police_id    │     │ id             │
│ name             │     │ road_name            │     │ name           │
│ phone            │     │ safety_score         │     │ phone          │
│ address          │     │ lighting             │     │ email          │
│ geom (Point)     │     │ crowd_level          │     └────────────────┘
│ active           │     │ cctv_present         │            │
└──────────────────┘     │ incidents_reported   │            │
                         │ geom (LineString)    │     ┌──────┴─────────┐
                         └──────────────────────┘     │incident_reports│
                                                      ├────────────────┤
┌──────────────────┐     ┌──────────────────────┐     │ road_id        │
│ community_posts  │     │ community_comments   │     │ user_id        │
├──────────────────┤     ├──────────────────────┤     │ description    │
│ id               │◄────│ post_id              │     │ geom (Point)   │
│ clerk_user_id    │     │ clerk_user_id        │     └────────────────┘
│ content          │     │ content              │
│ category         │     │ author_name          │     ┌────────────────┐
│ is_sos           │     └──────────────────────┘     │community_likes │
│ sos_lat/lng      │                                  ├────────────────┤
│ author_name      │◄─────────────────────────────────│ post_id        │
└──────────────────┘                                  │ clerk_user_id  │
                                                      └────────────────┘

Triggers:

• trg_police_proximity — auto-assigns the nearest police station to new road segments
• trg_incident_count — syncs incident count when new reports are filed

Views:

• v_road_safety — pre-computed final safety scores with time-of-day adjustments

---

📱 Pages

Page	Route	Description
🏠 Landing	/	Hero section, feature showcase, how-it-works
🗺️ Map	/map	Interactive safety map with routing (auth required)
📖 How It Works	/how-it-works	Step-by-step guide to using Avaya
🛡️ Safety Tips	/safety-tips	Curated safety advice for women travelers
ℹ️ About	/about	About the project and team
📞 Contact	/contact	Contact form and information
🔑 Sign In	/sign-in	Clerk authentication
📝 Sign Up	/sign-up	New user registration

---

🌟 Why "Avaya"?

The name comes from Abhaya (अभय) — a Sanskrit word meaning fearless or without fear.

Avaya is our promise: a world where women can navigate any city, any street, at any hour — without fear.

"Take up space. We'll handle the safety."

---

👥 Contributing

We welcome contributions! Here's how to get started:

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

---

📄 License

This project is licensed under the ISC License.

---

Built with ❤️ for a safer world
Avaya — Let her walk safely.