WardWatch

Civic observability for Bengaluru. Treats municipal infrastructure as a distributed system — complaints are telemetry, department transfers are trace spans, unresponsive offices are dead zones ("ghost offices"), and outage-correlated scam spikes are anomalies.

A single Next.js 14 app: dashboard + 41 API routes + 5 LLM agents. MongoDB for storage, Groq (free tier, Llama 3.3 70B) for the agents.

Quick start

git clone https://github.com/chemicoholic21/ward_watch.git
cd ward_watch
cp .env.example .env.local
npm install
docker-compose up -d mongo            # or set MONGO_URI to an Atlas cluster
npm run seed                          # 5k complaints + 500 scams + wards
npm run dev                           # http://localhost:3000

Optional — to enable the LLM agent chat:

echo "GROQ_API_KEY=gsk_..." >> .env.local   # free key: console.groq.com/keys

Stack

Next.js 14 (App Router) · TypeScript · Tailwind CSS · MongoDB · Vercel AI SDK + Groq (Llama 3.3 70B) · Vercel

Features

Dashboard

Single-page dashboard with an Apple-minimal black theme:

• Overview — total complaints, ghost office count, active scam alerts, average resolution time with trend indicators
• Ghost Office Leaderboard — ranked unresponsive municipal offices with ghost scores (0–100), alert levels, and complaint breakdowns
• TrustLens — paste-a-suspicious-message analyzer returning risk level, trust score, and matched scam patterns
• Civic Health — zone-level grades (A–F) across complaint resolution metrics for East, West, North, South, and Central zones
• Intelligence Agents — interactive agent cards for natural-language queries against civic data

LLM Agents

Agent	Purpose
Ghost Hunter	Investigates unresponsive offices with concrete figures
Scam Detector	Triages suspicious messages, provides plain-language advice
Escalation Tracer	Traces complaint paths, identifies bottleneck departments
Civic Analyzer	General-purpose civic health Q&A
RTI Drafter	Drafts Right to Information applications with cited evidence

Two execution modes:

• POST /api/agents/chat — LLM-powered (Groq). Natural language in, narrative answer out. Requires GROQ_API_KEY.
• POST /api/agents/execute — Deterministic dispatch. Fast, predictable, no API key needed.

An OpenClaw orchestrator coordinates multi-agent workflows: Comprehensive Civic Analysis, Scam Investigation, and Complaint Deep Dive.

API Routes (41+)

• /api/complaints — CRUD + stats for civic complaints
• /api/ghost-offices — ghost office scores, rankings, heatmap data
• /api/trustlens — scam analysis, reports, outage correlation
• /api/search — full-text, faceted, semantic, and autocomplete search
• /api/analytics — dashboard stats, civic health, trends, geo analytics
• /api/wards — ward details, nearby wards, leaderboard, zone summary
• /api/actions — generate RTI applications, escalation letters, social media posts, report cards
• /api/health — basic, liveness, readiness, and detailed health checks

Data Models (6 MongoDB collections)

• civic_events — complaints with geo-location, timeline, escalation counts
• ghost_offices — unresponsiveness scores with contributing factors
• scam_reports — scam messages with risk indicators, matched patterns, trust scores
• escalation_traces — complaint journey traces with department spans (like distributed system traces)
• ward_metrics — ward-level aggregated health scores and rankings
• civic_vectors — embedding vectors for semantic search

Project structure

app/
  page.tsx                  # Single-page dashboard
  api/                      # 41+ API route handlers
    agents/                 # LLM chat, execute, status
    complaints/             # CRUD + stats
    ghost-offices/          # scores, rankings, heatmap
    trustlens/              # scam analysis, reports
    search/                 # full-text, faceted, semantic
    analytics/              # dashboard, civic-health, trends
    wards/                  # details, leaderboard, zones
    actions/                # RTI, escalation, social, report-card
    health/                 # basic, live, ready, detailed
lib/
  server/
    services/
      agents/               # LLM runtime, tools, helpers
      ghost-office/         # ghost score detector
      trustlens/            # regex-based scam classifier
      openclaw/             # multi-agent orchestrator
      mongodb/              # MongoService, query translator, agg evaluator
    config/                 # environment, MongoDB connection
scripts/
  seed-mongodb.mjs          # Database seeder
data/
  seed/                     # wards, departments, scam patterns JSON
  generators/               # synthetic data generators (Faker)
infrastructure/
  lambda/                   # AWS SAM template (4 Lambda functions)
  elasticsearch/            # index mappings, ingest pipelines
docs/                       # deployment, MongoDB setup, agents guide, demo script

Deploy

Vercel (recommended)

vercel --prod

Set MONGO_URI and GROQ_API_KEY in Vercel env vars. Deploys to Mumbai (bom1). Full walkthrough in docs/DEPLOYMENT_GUIDE.md.

Docker Compose

docker-compose up -d

Runs MongoDB 7.0, Mongo Express (port 8081), and the Next.js dev server (port 3000).

AWS (optional, feature-flagged)

Lambda functions for event processing, ghost office calculation, scam alerting, and Bedrock AI analysis. Gated by ENABLE_LAMBDA, ENABLE_BEDROCK, ENABLE_SNS env vars (default: false). See infrastructure/lambda/template.yaml.

Scripts

Command	Description
npm run dev	Start Next.js dev server
npm run build	Production build
npm run start	Start production server
npm run lint	Run ESLint
npm run seed	Seed MongoDB with 5k complaints, 500 scams, 45 ghost offices, 15 wards

Docs

• docs/DEPLOYMENT_GUIDE.md — Atlas + Vercel end-to-end walkthrough
• docs/MONGODB_SETUP.md — local Docker or Atlas setup
• docs/AGENTS_GUIDE.md — how the LLM agents work, how to add tools
• docs/DEMO_SCRIPT.md — 10–15 minute demo walkthrough

License

MIT