NagarSeva empowers citizens to report public infrastructure issues and unsafe areas using AI-powered analysis, real-time GPS tracking, and automatic routing to the correct government authority. The application works out of the box in demo mode without any external API keys or paid services.
🔗 Live Demo: https://nagar-seva-ai-xx-devv.vercel.app
- Features
- Pages & Routes
- Tech Stack
- Quick Start (Local Development)
- Running the Backend
- External Services
- API Endpoints
- Project Structure
- Demo Credentials
- Screenshots
- Contributing
- License
| Feature | Description |
|---|---|
| 🤖 AI-Powered Complaint Filing | Describe or upload images; AI classifies, categorizes, and routes issues to the correct department automatically |
| 🗺️ Interactive Safety Map | Full-screen Leaflet map with severity-coded markers, unsafe zone indicators, and category/severity/time-of-day filters |
| 🏢 Smart Department Routing | AI determines the correct government department for each complaint based on keywords and context |
| 📊 Real-time Tracking | Track complaints from submission → assigned → in progress → resolved with a detailed status timeline |
| 📈 Public Dashboard | Live stats cards, category breakdown bar chart, monthly trend line chart, complaint distribution pie chart, and recent complaints table |
| 👮 Authority Dashboard | Full complaint management panel with search, department/severity/status filters, status update buttons, escalation indicators for overdue complaints |
| 📍 GPS Auto-detection | Browser Geolocation API with OpenStreetMap reverse geocoding for precise location |
| 🙈 Anonymous Reporting | Report issues without revealing your identity — toggle on/off during submission |
| 🔐 Demo Authentication | Instant one-click login as Citizen or Authority — no registration required |
| 💾 Persistent Storage | SQLite backend stores all complaints persistently across server restarts |
| 📱 Fully Responsive | Adaptive layout works seamlessly on mobile, tablet, and desktop |
| Route | Page | Description |
|---|---|---|
/ |
Landing | Hero section with stats, feature cards, how-it-works walkthrough, and CTA |
/report |
Report Issue | 3-step wizard: describe issue (with AI analysis), add location & photo, review & submit |
/safety-map |
Safety Map | Full-screen Leaflet map with severity-coded markers, unsafe zone circles, and multi-dimensional filters |
/dashboard |
Public Dashboard | Stat cards, category breakdown bar chart, monthly trend line chart, department workload bars, pie chart, recent complaints table |
/track |
Track Complaint | Search by tracking ID with animated status timeline and full complaint details |
/authority |
Authority Dashboard | Complaint management with search, department/severity/status filters, expandable details, status update actions, escalation warnings |
/auth/login |
Login | Email/password form plus one-click demo login buttons for Citizen and Authority roles |
/auth/register |
Register | Create a new account (demo mode — works without email verification) |
/about |
About | Mission statement, core values, tech stack overview, team section, contact information |
| Technology | Purpose |
|---|---|
| React 18 + TypeScript | Component-based UI with full type safety |
| Vite | Fast development server and optimized production builds |
| TailwindCSS | Utility-first responsive styling with custom design system |
| Framer Motion | Smooth page transitions and micro-interactions |
| React Router v6 | Client-side routing with lazy loading support |
| React Query v5 | Server state management, caching, and background refetching |
| Leaflet + React Leaflet | Interactive maps with custom markers and overlays |
| Lucide React | Consistent, lightweight icon system |
| Recharts | Responsive bar, line, and pie charts for the dashboard |
| Technology | Purpose |
|---|---|
| FastAPI (Python) | High-performance async REST API with automatic OpenAPI docs |
| Pydantic v2 | Request/response validation with strict typing |
| Uvicorn | ASGI server for production-ready Python apps |
| SQLite (built-in) | Zero-configuration persistent storage — no database server needed |
git clone https://github.com/xx-devvv/NagarSevaAI.git
cd NagarSevaAI/client
npm install
npm run devThe frontend development server starts on port 5173.
Open a second terminal:
cd NagarSevaAI/server
pip install fastapi uvicorn pydantic pydantic-settings python-dotenv python-multipart
python -m uvicorn app.main:app --reload --port 8000The API server starts on port 8000. Interactive API documentation is available at /docs.
Open https://nagar-seva-ai-xx-devv.vercel.app or run locally. Everything works immediately with:
- 10 pre-seeded demo complaints stored in SQLite
- Mock AI analysis — no API key required
- One-click demo login for Citizen and Authority roles
The backend provides a RESTful API at port 8000. In demo mode, it works entirely offline:
cd server
pip install -r requirements.txt
python -m uvicorn app.main:app --reload --port 8000Demo behavior:
- Storage uses SQLite (
nagarseva.db) — created automatically on first run - 10 sample complaints are seeded when the database is empty
- All endpoints respond with realistic mock data
- AI analysis uses keyword matching instead of external APIs
- No environment variables or configuration files are required
Optional configuration: Copy server/.env.example to server/.env to customize settings.
| Service | Purpose | Demo Fallback |
|---|---|---|
| Google Gemini AI | Enhanced AI complaint analysis | Keyword-based mock analysis |
| Firebase Auth | Authentication provider | Local state with localStorage |
| Google Maps / Mapbox | Map tiles | Leaflet + OpenStreetMap (free) |
| Cloudinary | Image storage | Upload works without cloud storage |
| PostgreSQL | Production database | SQLite (zero-config, built-in) |
| Redis + Celery | Background task processing | Not required for demo |
⚠️ Note: The live demo deploys the frontend only. It gracefully falls back to built-in demo data when the backend is unreachable — all features work visually. For the full experience with the persistent SQLite backend, run locally.
No paid API keys are needed. The app runs fully in demo mode out of the box.
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Health check — returns status and timestamp |
POST |
/api/complaints |
Create a new complaint (multipart form data) |
GET |
/api/complaints |
List complaints (supports status, category, severity, department, page, limit filters) |
GET |
/api/complaints/{id} |
Get a single complaint by internal ID |
PATCH |
/api/complaints/{id}/status |
Update complaint status with optional notes |
GET |
/api/complaints/track/{tracking_id} |
Get tracking info by tracking ID (e.g., NS-A7F3) |
GET |
/api/dashboard/stats |
Dashboard statistics with category breakdown, department workload, and monthly trends |
POST |
/api/ai/analyze |
AI analysis of complaint text |
POST |
/api/ai/analyze-image |
AI analysis of uploaded image |
Interactive API docs are available at /docs when running the backend locally.
NagarSevaAI/
├── client/ # React + TypeScript Frontend
│ ├── public/ # Static assets (favicon, etc.)
│ ├── src/
│ │ ├── components/
│ │ │ ├── layout/ # Navbar, Footer
│ │ │ └── ui/ # Button, shared UI primitives
│ │ ├── hooks/ # useAuth, useGeolocation
│ │ ├── pages/ # Landing, Report, SafetyMap, Dashboard,
│ │ │ # Track, Authority, Auth, About
│ │ ├── services/ # API client with snake_case↔camelCase conversion
│ │ ├── types/ # TypeScript interfaces and enums
│ │ ├── utils/ # cn() class merge utility
│ │ ├── config/ # Environment configuration
│ │ ├── App.tsx # Router configuration
│ │ ├── main.tsx # Application entry point
│ │ └── index.css # Tailwind directives and custom component classes
│ ├── tailwind.config.js # Custom design system theme
│ ├── vite.config.ts # Vite configuration with API proxy
│ └── package.json # Dependencies
├── server/ # FastAPI Backend
│ ├── app/
│ │ ├── api/v1/ # REST API route handlers
│ │ ├── models/ # Pydantic schemas (Complaint, User, DashboardStats, etc.)
│ │ ├── services/ # Storage (SQLite), AI analysis service
│ │ ├── config.py # Application settings
│ │ └── main.py # FastAPI app creation and middleware
│ ├── .env.example # Optional environment variables
│ └── requirements.txt # Python dependencies
├── .gitignore
└── README.md
No registration is required. On the login page, click one of these buttons:
| Role | Button | What You Can Do |
|---|---|---|
| 👤 Citizen | Continue as Citizen (Demo) |
Report issues, view safety map, explore dashboard, track complaints |
| 🏛️ Authority | Continue as Authority (Demo) |
All citizen features plus the Authority Dashboard at /authority with complaint management, status updates, and escalation alerts |
| Page | Preview |
|---|---|
| Landing | Hero with stats, feature grid, how-it-works, and CTA |
| Report Issue | 3-step wizard with AI analysis, image upload, geolocation |
| Safety Map | Full-screen Leaflet map with severity markers and filters |
| Dashboard | Stats cards, bar/line/pie charts, department workload, recent complaints table |
| Track | Tracking ID search with animated status timeline |
| Authority | Complaint list with filters, expandable details, status actions, escalation badges |
Visit the live demo to see all pages in action.
Contributions are welcome! Here's how to get started:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is developed as part of a civic technology initiative. All rights reserved.
Made with ❤️ for safer communities.