🔍 CivicLens

AI-Powered Civic Issue Reporting & Resolution Platform

Report infrastructure issues · AI-verified image analysis · Real-time tracking · Admin & Worker portals

📖 Overview

CivicLens is a full-stack civic issue reporting platform that empowers citizens to report infrastructure problems (potholes, broken streetlights, garbage overflow, drainage issues, etc.) using AI-powered image analysis. The platform features three interconnected applications — a Citizen App, an Admin Panel, and a Worker App — creating a complete end-to-end lifecycle for civic issue management, from submission to resolution.

Key Highlights

🤖 AI-Powered: Google Gemini automatically generates titles, descriptions, and categories from uploaded images
🔒 AI Image Verification: Sightengine detects and blocks AI-generated/fake images to ensure authenticity
🗺️ Interactive Maps: Leaflet-powered map with severity-coded markers and location-based geocoding
📊 Real-time Updates: Supabase real-time subscriptions for live status tracking
📱 Mobile-First + Native: Built for mobile web with Capacitor for Android APK builds
📧 Email Notifications: Automated email alerts when reports are assigned to officers
📄 PDF Reports: Client-side A4 PDF generation with embedded images and styled layout
🌐 Offline Support: SQLite-based caching for offline report browsing on native devices

🏗️ Architecture

CivicLens/
├── src/                  # 📱 Citizen App (Vite + React + TypeScript)
├── admin/                # 🛡️ Admin Panel (Vite + React + TypeScript)
├── worker-app/           # 👷 Worker App (Vite + React + TypeScript)
├── backend/              # ⚙️ Backend API (Node.js + Express)
├── android/              # 📲 Capacitor Android project
├── supabase/             # 🗄️ Supabase migrations & config
└── *.sql                 # 📋 Database schema files

Tech Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, TailwindCSS, Shadcn/UI, Radix UI, Framer Motion
Backend	Node.js, Express, Multer, Nodemailer, Sharp
Database	Supabase (PostgreSQL) with Row-Level Security & Real-time subscriptions
AI/ML	Google Gemini 2.5 Flash (vision), Sightengine (AI image detection)
Maps	Leaflet + React-Leaflet, Nominatim (geocoding via backend proxy)
Auth	Clerk (citizen app), Custom auth (admin & worker)
Mobile	Capacitor (Android), SQLite (offline storage)
PDF	pdf-lib (client-side A4 report generation)
Hosting	Render (backend), Supabase (database), Any static host (frontend)

🔄 End-to-End Workflow

flowchart TD
    A[👤 Citizen Opens App] --> B[📸 Uploads Photo of Issue]
    B --> C{🔒 AI Image Verification}
    C -->|Fake/AI Image| D[❌ Image Rejected]
    C -->|Real Image| E[🤖 Gemini AI Analyzes Image]
    E --> F[Auto-fills Title, Description & Category]
    F --> G[📍 Citizen Picks Location on Map]
    G --> H[👁️ Issue Preview Screen]
    H --> I[✅ Submit to Supabase Database]
    I --> J[📊 Admin Dashboard - Real-time]
    J --> K[🛡️ Admin Reviews & Assigns to Worker]
    K --> L[📧 Email Notification Sent to Worker]
    L --> M[👷 Worker App - Views Assigned Task]
    M --> N[🔧 Worker Resolves Issue]
    N --> O[📸 Worker Uploads Resolution Proof]
    O --> P[✅ Admin Marks as Resolved]
    P --> Q[📱 Citizen Sees Updated Status in Real-time]
    Q --> R[📄 Download PDF Report]

Detailed Flow

Citizen submits a report → Takes a photo or uploads from gallery
AI Image Verification → Sightengine checks if the image is real (≥85% human probability required)
Gemini AI Analysis → Automatically generates title, description, and category from the image
Location Selection → Pick location on an interactive Leaflet map with reverse geocoding
Preview & Submit → Review all details before submitting to Supabase
Real-time Sync → Report instantly appears on Admin Dashboard via Supabase real-time
Admin Action → Admin reviews, assigns to officer/worker, sends email notification
Worker Resolution → Worker views assigned tasks, resolves, uploads proof
Status Tracking → Citizen tracks progress (Submitted → Viewed by Admin → Resolved)
PDF Download → Generate and download a professional A4 PDF report

📱 Application Modules

1. Citizen App (`/src`)

The main mobile-first web application for citizens to report and track civic issues.

Feature	Description
Onboarding	Splash screen → Guided onboarding → Sign up / Login via Clerk
Home Dashboard	Weather widget, report statistics, quick actions, latest pending issues feed
Report an Issue	Photo upload → AI verification → Gemini auto-fill → Location picker → Preview → Submit
My Reports	View all submitted reports with status filters (Pending/Resolved/Rejected)
Report Details	Full issue details, progress timeline, upvote system, admin view status, PDF download
Map View	Interactive Leaflet map with severity-coded markers, geolocation, map clustering
Nearby Alerts	Location-aware feed of reported issues sorted by proximity
Profile	View & edit profile, manage account settings
Offline Mode	SQLite-based caching of reports, weather, stats for offline browsing (native)
Push Notifications	FCM token registration for push notification support (native)

Key Pages: Splash → Onboarding → Login / Signup → Home → ReportIssue → ChooseLocation → IssuePreview → MyReports → ReportDetails → MapView → NearbyAlerts → Profile → EditProfile

2. Admin Panel (`/admin`)

A desktop-optimized administrative dashboard for municipal authorities.

Feature	Description
Dashboard	Real-time stats (total, pending, resolved, rejected), recent reports table, summary panel
Issues Management	Full list of all reports with sorting, filtering, and bulk actions
Report Details	Detailed view, assign to officer, update status, add resolution notes
Worker Management	Register, edit, and manage field workers/officers
Approvals	Review and approve/reject submitted reports
Map View	Geo-visualize all reported issues across the city
Analytics	Charts and statistics for report trends, category breakdown
Profile	Admin profile and account management
Email Notifications	Sends styled HTML emails to officers when reports are assigned

Key Pages: SignIn → Dashboard → Issues → ReportDetails → Workers → Approvals → MapPage → Analytics → Profile

3. Worker App (`/worker-app`)

A mobile-first application for field workers to manage assigned tasks.

Feature	Description
Splash & Login	Animated splash screen → Worker credential login
Onboarding	Interactive walkthrough for new workers
Issues Near You	Browse civic issues nearby with location context
My Tasks	View all assigned tasks with status tracking
Issue Details	View full issue details, upload resolution proof, mark as resolved
Task Review	Review completed tasks and upload verification images
Profile	Worker profile and settings management
AI Verification	Resolution proof images are verified for authenticity

Key Pages: SplashScreen → LoginPage → OnboardingPage → IssuesListPage → IssueDetailsPage → TaskReviewPage → ProfilePage

4. Backend API (`/backend`)

A Node.js/Express server handling sensitive operations and third-party integrations.

Endpoint	Method	Description
`/health`	GET	Health check
`/detect-ai-image`	POST	AI image detection via Sightengine (multipart upload)
`/api/reverse-geocode`	GET	Reverse geocoding with Supabase caching (~200m radius)
`/api/search-location`	GET	Forward geocoding (text → coordinates) via Nominatim proxy
`/api/send-email`	POST	Send generic HTML email
`/api/send-report-assignment`	POST	Send styled report assignment email to officers
`/api/notifications/register`	POST	Register FCM push notification token
`/api/notifications/unregister`	POST	Unregister FCM token (on logout)
`/api/notifications/tokens/:userId`	GET	Get active tokens for a user
`/api/clear-cache`	POST	Clear geocoding cache (debug)
`/api/view-cache`	GET	View cached geocoding entries (debug)

🔑 Environment Variables

⚠️ IMPORTANT: Never commit .env files. Use .env.example as a template.

The project uses environment variables across four applications. Copy the respective .env.example file to .env in each directory.

Required API Keys

Service	Purpose	Get it from
Clerk	User authentication (citizen app)	clerk.com
Supabase	Database, auth, real-time subscriptions	supabase.com
Google Gemini	AI image analysis (vision model)	makersuite.google.com
OpenWeatherMap	Weather data for home dashboard	openweathermap.org
Sightengine	AI-generated image detection	sightengine.com
Gmail SMTP	Email notifications (backend)	Google App Passwords

Configuration Files

CivicLens/.env.example        → Citizen App (VITE_* prefixed)
CivicLens/backend/.env.example → Backend Server
CivicLens/admin/.env.example   → Admin Panel
CivicLens/worker-app/.env.example → Worker App

🚀 Getting Started

Prerequisites

Node.js ≥ 18
npm or bun
A Supabase project (free tier works)
API keys for Clerk, Gemini, OpenWeatherMap, and Sightengine

1. Clone the Repository

git clone https://github.com/KanishJebaMathewM/CivicLens.git
cd CivicLens

2. Database Setup

Run the following SQL files in your Supabase SQL Editor (in order):

# 1. Core reports table
database-schema-reports.sql

# 2. Admin tracking columns
database-schema-admin-tracking.sql

# 3. Officers table
CREATE_OFFICERS_TABLE.sql

# 4. Worker flow migration
WORKER_FLOW_MIGRATION.sql

# 5. Any missing columns
ADD_MISSING_COLUMNS.sql

3. Setup Citizen App (Root)

# Install dependencies
npm install

# Copy environment template and fill in your keys
cp .env.example .env

# Start development server
npm run dev

The app will be available at http://localhost:5173

4. Setup Backend

cd backend

# Install dependencies
npm install

# Copy environment template and fill in your keys
cp .env.example .env

# Start development server (with auto-restart)
npm run dev

The API will be available at http://localhost:3001

5. Setup Admin Panel

cd admin

# Install dependencies
npm install

# Copy environment template and fill in your keys
cp .env.example .env

# Start development server
npm run dev

The admin panel will be available at http://localhost:5174

6. Setup Worker App

cd worker-app

# Install dependencies
npm install

# Copy environment template and fill in your keys
cp .env.example .env

# Start development server
npm run dev

The worker app will be available at http://localhost:5175

7. Android Build (Optional)

# From root directory
npm run build              # Build the Vite app
npx cap sync android       # Sync web assets to Android
npx cap open android       # Open in Android Studio

🗄️ Database Schema

`reports` Table (Core)

Column	Type	Description
`id`	UUID	Primary key (auto-generated)
`title`	TEXT	Issue title
`description`	TEXT	Detailed description
`category`	TEXT	Road Issues, Garbage, Water/Drainage, Streetlight, etc.
`status`	TEXT	`pending` / `resolved` / `rejected`
`severity`	TEXT	`low` / `medium` / `high`
`location_name`	TEXT	Human-readable address
`latitude`	DECIMAL	GPS latitude
`longitude`	DECIMAL	GPS longitude
`image_url`	TEXT	Uploaded image URL/base64
`user_id`	TEXT	Reporter's user ID
`upvotes`	INTEGER	Community upvote count
`viewed_by_admin`	BOOLEAN	Whether admin has seen it
`admin_viewed_at`	TIMESTAMP	When admin viewed it
`resolved_by`	TEXT	Worker who resolved
`resolved_at`	TIMESTAMP	Resolution timestamp
`created_at`	TIMESTAMP	Submission time
`updated_at`	TIMESTAMP	Last update time

Supporting Tables

reverse_geocache — Caches reverse geocoding results (~200m radius)
fcm_tokens — FCM push notification tokens per user
officers — Municipal officers/workers registry
notifications — Notification events for broadcasts

🤖 AI Features

1. Gemini Vision Analysis

Auto-generates issue title (max 8 words)
Auto-generates concise description (1–2 sentences)
Auto-suggests category from predefined list
Uses gemini-2.5-flash-preview model with system instructions

2. Sightengine AI Image Detection

Detects AI-generated/fake images before submission
Images must be ≥ 85% human probability to pass
Compresses images server-side (via Sharp) before analysis
60-second timeout with graceful fallback

📄 PDF Report Generation

CivicLens generates professional A4 PDF reports client-side using pdf-lib:

Branded header with CivicLens logo and status badge
Issue details — title, category, severity, date, location
Description section with multi-line text wrapping
Evidence images — original issue + resolution proof (side-by-side)
Footer with generation timestamp and page numbers
Supports both web download and native (Capacitor Filesystem) save

🌐 Offline Support

On native Android builds, CivicLens uses Capacitor SQLite for offline data:

Cached Data	Auto-Refresh
Home feed reports	On reconnect
Nearby alerts	On reconnect
My reports list	On reconnect
Map markers	On reconnect
Weather data	1-hour TTL
User profile	On login
Report statistics	On reconnect
Location history	Last 20 entries

🔒 Security

All API keys are loaded from environment variables (.env)
.env files are excluded from version control via .gitignore
Backend uses Supabase Service Role Key (never exposed to client)
Client uses Supabase Anon Key with Row-Level Security (RLS)
Sightengine API credentials are server-side only
SMTP credentials are server-side only
CORS enabled on backend for cross-origin requests
google-services.json is gitignored (download from Firebase Console)

📁 Project Structure

CivicLens/
├── src/                        # 📱 Citizen App
│   ├── pages/                  # All page components
│   │   ├── Home.tsx            # Dashboard with weather, stats, issues
│   │   ├── ReportIssue.tsx     # Report form with AI analysis
│   │   ├── ChooseLocation.tsx  # Interactive map location picker
│   │   ├── IssuePreview.tsx    # Preview & submit report
│   │   ├── MyReports.tsx       # User's submitted reports
│   │   ├── ReportDetails.tsx   # Full report with progress tracker
│   │   ├── MapView.tsx         # City-wide issue map
│   │   ├── NearbyAlerts.tsx    # Proximity-based issue feed
│   │   ├── Profile.tsx         # User profile
│   │   └── ...
│   ├── services/               # Business logic
│   │   ├── geminiVision.ts     # Gemini AI image analysis
│   │   ├── aiImageDetectionService.ts  # Sightengine client
│   │   ├── WeatherService.ts   # OpenWeatherMap integration
│   │   ├── offlineService.ts   # SQLite offline caching
│   │   ├── pdfService.ts       # A4 PDF generation
│   │   ├── notificationService.ts  # FCM token management
│   │   ├── upvoteService.ts    # Upvote toggle logic
│   │   └── authService.ts      # Auth state management
│   ├── components/             # Reusable UI components
│   ├── hooks/                  # Custom React hooks
│   ├── lib/                    # Utilities (Supabase client, etc.)
│   └── utils/                  # Helper functions
│
├── admin/src/                  # 🛡️ Admin Panel
│   ├── pages/admin/            # Admin page components
│   ├── services/               # Admin business logic
│   ├── components/             # Admin UI components
│   └── contexts/               # Auth context
│
├── worker-app/src/             # 👷 Worker App
│   ├── pages/                  # Worker page components
│   ├── services/               # Worker business logic
│   └── components/             # Worker UI components
│
├── backend/                    # ⚙️ Express API Server
│   ├── server.js               # Main server with all routes
│   └── services/               # Backend services
│       └── aiImageDetection.js # Sightengine integration
│
├── android/                    # 📲 Capacitor Android project
├── *.sql                       # Database migration scripts
├── capacitor.config.ts         # Mobile build config
└── package.json                # Root dependencies

🛠️ Scripts

Citizen App (Root)

npm run dev       # Start Vite dev server
npm run build     # Production build
npm run preview   # Preview production build
npm run lint      # Run ESLint

Backend

cd backend
npm run dev       # Start with auto-restart (--watch)
npm start         # Start production server

Admin Panel

cd admin
npm run dev       # Start Vite dev server
npm run build     # Production build

Worker App

cd worker-app
npm run dev       # Start Vite dev server
npm run build     # Production build

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Copy .env.example → .env and configure your keys
Make your changes
Commit (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is open-source. See the repository for license details.

Built with ❤️ by the CivicLens Team

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
.vscode		.vscode
admin		admin
android		android
backend		backend
public		public
scripts		scripts
src		src
supabase		supabase
worker-app		worker-app
.env.example		.env.example
.gitignore		.gitignore
ADD_MISSING_COLUMNS.sql		ADD_MISSING_COLUMNS.sql
AI_IMAGE_DESCRIPTION_DOCUMENTATION.md		AI_IMAGE_DESCRIPTION_DOCUMENTATION.md
COMPLETE_IMPLEMENTATION_SUMMARY.md		COMPLETE_IMPLEMENTATION_SUMMARY.md
CREATE_OFFICERS_TABLE.sql		CREATE_OFFICERS_TABLE.sql
FIX_REPORT_SUBMISSION.sql		FIX_REPORT_SUBMISSION.sql
LICENSE		LICENSE
README.md		README.md
WORKER_FLOW_MIGRATION.sql		WORKER_FLOW_MIGRATION.sql
bun.lockb		bun.lockb
capacitor.config.ts		capacitor.config.ts
client_lint.txt		client_lint.txt
client_lint_2.txt		client_lint_2.txt
client_lint_3.txt		client_lint_3.txt
client_lint_4.txt		client_lint_4.txt
components.json		components.json
database-schema-admin-tracking.sql		database-schema-admin-tracking.sql
database-schema-reports.sql		database-schema-reports.sql
eslint.config.js		eslint.config.js
google-services.example.json		google-services.example.json
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
qr.svg		qr.svg
tailwind.config.ts		tailwind.config.ts
test-realtime.js		test-realtime.js
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
verify-database.sql		verify-database.sql
vite.config.ts		vite.config.ts
vite.config.ts.timestamp-1768055738056-c7238489349ad.mjs		vite.config.ts.timestamp-1768055738056-c7238489349ad.mjs

Folders and files

Latest commit

History

Repository files navigation

🔍 CivicLens

📖 Overview

Key Highlights

🏗️ Architecture

Tech Stack

🔄 End-to-End Workflow

Detailed Flow

📱 Application Modules

1. Citizen App (/src)

2. Admin Panel (/admin)

3. Worker App (/worker-app)

4. Backend API (/backend)

🔑 Environment Variables

Required API Keys

Configuration Files

🚀 Getting Started

Prerequisites

1. Clone the Repository

2. Database Setup

3. Setup Citizen App (Root)

4. Setup Backend

5. Setup Admin Panel

6. Setup Worker App

7. Android Build (Optional)

🗄️ Database Schema

reports Table (Core)

Supporting Tables

🤖 AI Features

1. Gemini Vision Analysis

2. Sightengine AI Image Detection

3. Issue Categories (AI-classified)

📄 PDF Report Generation

🌐 Offline Support

🔒 Security

📁 Project Structure

🛠️ Scripts

Citizen App (Root)

Backend

Admin Panel

Worker App

🤝 Contributing

📝 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Citizen App (`/src`)

2. Admin Panel (`/admin`)

3. Worker App (`/worker-app`)

4. Backend API (`/backend`)

`reports` Table (Core)

Packages