🛡️ CityWatch — AI-Powered Road Hazard Reporting

An AI-powered system for citizens to report road hazards (potholes, broken signals, flooding, etc.) with automatic classification and priority scoring.

Tech Stack

Layer	Technology
Frontend	React 19 + Vite + Tailwind CSS 4
Backend	Node.js + Express
Database	Neon (Serverless PostgreSQL)
Auth	Clerk (Google OAuth)
Storage	Cloudinary (Image CDN)
Realtime	Pusher (WebSocket events)
ML	Python + FastAPI + CLIP ViT-B/32

Project Structure

├── client/          # React frontend (Vite)
├── server/          # Express API server
├── ml-service/      # Python ML microservice
└── db/              # Database schema

Setup

1. Database Setup (Neon)

1. Create a project at neon.tech
2. Run db/schema.sql in the Neon SQL Editor
3. Copy the connection string for your .env

2. Auth Setup (Clerk)

1. Create an app at clerk.com
2. Enable Google OAuth in Clerk Dashboard → User & Authentication → Social Connections
3. Copy the Publishable Key (for client) and Secret Key (for server)

3. Cloudinary Setup

1. Create an account at cloudinary.com
2. Copy Cloud Name, API Key, and API Secret from the dashboard

4. Pusher Setup

1. Create an app at pusher.com
2. Copy App ID, Key, Secret, and Cluster

5. Client Setup

cd client
cp .env.example .env    # Add your Clerk publishable key + Pusher key
npm install
npm run dev

6. Server Setup

cd server
cp .env.example .env    # Add Neon URL + Clerk + Cloudinary + Pusher keys
npm install
npm run dev

7. ML Service (optional)

See ml-service/ for setup. The backend falls back to keyword-based classification if the ML service is unavailable.

cd ml-service
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
python download_model.py
uvicorn app.main:app --reload --port 8000

Roles

Role	Access	How to assign
client	Submit complaints, view own reports	Default on signup
company	Map dashboard, manage complaints	Update profiles.role in Neon
admin	User management, analytics, full access	Update profiles.role in Neon

Environment Variables

Server (server/.env)

DATABASE_URL=postgresql://...          # Neon connection string
CLERK_SECRET_KEY=sk_test_...           # Clerk secret key
CLOUDINARY_CLOUD_NAME=...             # Cloudinary cloud name
CLOUDINARY_API_KEY=...                # Cloudinary API key
CLOUDINARY_API_SECRET=...             # Cloudinary API secret
PUSHER_APP_ID=...                     # Pusher app ID
PUSHER_KEY=...                        # Pusher key
PUSHER_SECRET=...                     # Pusher secret
PUSHER_CLUSTER=us2                    # Pusher cluster
ML_SERVICE_URL=http://localhost:8000  # ML microservice URL
CLIENT_URL=http://localhost:5173      # Frontend URL (for CORS)

Client (client/.env)

VITE_CLERK_PUBLISHABLE_KEY=pk_test_... # Clerk publishable key
VITE_PUSHER_KEY=...                    # Pusher key (same as server)
VITE_PUSHER_CLUSTER=us2               # Pusher cluster