CityTrack

GitHub: 0xarchit/CityTrack
Live Demo: https://city-track-seven.vercel.app

Problem Statement

Traditional urban governance is plagued by:

• Manual Bottlenecks: Every report sits in a queue waiting for human categorization
• Redundancy: Multiple citizens report the same issue, creating duplicate tickets
• Data Black Holes: Citizens rarely receive feedback on their reports
• Subjective Prioritization: Urgent issues treated the same as minor ones

Features

• Anti-Fraud Reporting: Mandatory live camera and high-precision GPS lock
• AI-Powered Validation: Automatic classification using YOLOv8
• Smart Deduplication: Geospatial clustering to merge similar reports
• Dynamic Priority Assignment: Context-aware urgency levels with SLA enforcement
• Intelligent Routing: Automatic department and worker assignment
• Real-Time Tracking: Live progress updates for citizens
• Proof of Resolution: Workers must upload "After" photos to close tickets

System Architecture

CityTrack is an autonomous, event-driven operating system for smart cities that transforms civil infrastructure maintenance. The system leverages AI agents to instantly detect, validate, and route urban issues without human fatigue or bias.

The "Issue Packet"

Every interaction starts with an Issue Packet - an immutable, atomic unit of civic data:

• Evidence: Primary visual proof captured via mandatory live camera
• Context: High-precision GPS (< 10m accuracy), Compass Heading, Device Metadata
• Intent: User-provided description, enhanced by NLP

Anti-Fraud Enforcement

1. Live Camera Only: Users MUST capture photos live, preventing repurposing of old images
2. GPS Precision Lock: Submission blocked unless GPS accuracy < 10 meters
3. Identity Binding: Reports cryptographically linked to verified Google Identity (Supabase Auth)

System Flow Diagram

graph TD
    A[Citizen Mobile App] -->|Issue Packet| B[FastAPI Backend]
    B --> C[Event Bus]
    
    subgraph "Autonomous Agent Pipeline"
        C --> D[Vision Agent]
        D -->|Annotated Data| E[Geo-Deduplicate Agent]
        E -->|Clustered Info| F[Priority Agent]
        F -->|Urgency Level| G[Routing Agent]
        G -->|Assignment| H[Notification Agent]
    end
    
    H --> I[Worker Dashboard]
    H --> J[Admin Portal]
    H --> K[Citizen Updates]
    
    subgraph "Data Layer"
        L[(PostgreSQL)]
        M[(Supabase Storage)]
    end
    
    D -.-> M
    E -.-> L

Client Ecosystem

1. Citizen Mobile App (The Sensors)

Built with React Native + Expo (TypeScript)

• Offline-First: Caches reports locally and syncs when connection returns
• Real-Time Tracking: Server-driven events update processing screen live
• Gamification: Civic points for verified reports (Planned)

2. Admin Command Center (The Control)

Built with Next.js 16 (App Router) + Tailwind CSS

• Role-Based Access Control (RBAC): Super Admin, Department Admin, Worker Dashboard
• Visual Intelligence: Heatmaps and density plots for infrastructure zones

3. Worker Interface (The Hands)

Mobile-First Web View

• Task List: Priority-sorted list of jobs
• Navigation: One-tap deep link to Google Maps
• Proof of Resolution: Vision Agent verifies fix photos against originals

The Autonomous Pipeline

Stage 1: The Senses (Input & Validation)

Vision Agent: The "Eyes"

• Uses fine-tuned YOLOv8s model to scan incoming images
• Automatically discards irrelevant images (selfies, blurry photos)
• Identifies defects (Pothole, Debris, Graffiti) with confidence scores

Geo-Temporal Deduplication Agent: The "Memory"

• Uses bounding box queries and haversine distance calculation
• Merges reports into clusters, increasing urgency score

Stage 2: The Brain (Decision Making)

Priority Agent: The "Judge"

• Combines Vision Confidence + Location Context + Repeat Count
• Assigns dynamic SLA deadlines (e.g., 4 hours for Critical)

Routing Agent: The "Dispatcher"

• Matches issue category to Department and assigns workers by geolocation and load

Stage 3: The Enforcers (Execution)

SLA Watchdog Agent: The "Timekeeper"

• Analyzes context of delayed issues, not just the timer
• Triggers warnings at 50% and 20% remaining time

Notification Agent: The "Messenger"

• Pushes updates to Citizen, Worker, and Admin simultaneously
• Email notifications to stakeholders

Project Structure

/
├── Backend/              # Core Logic (FastAPI + Async SQLAlchemy)
│   ├── agents/           # 7 Autonomous Agents
│   │   ├── vision/       # Vision Agent (YOLOv8)
│   │   ├── geoDeduplicate/ # Geo-Temporal Deduplication
│   │   ├── priority/     # Priority Assignment
│   │   ├── routing/      # Department & Worker Routing
│   │   ├── sla/          # SLA Monitoring & Watchdog
│   │   ├── escalation/   # Escalation Management
│   │   └── notification/ # Omnichannel Notifications
│   ├── api/              # Stateless REST Endpoints
│   ├── core/             # Shared Infrastructure
│   ├── database/         # Database Layer
│   ├── orchestration/    # Agent Base Classes
│   └── services/         # External Services
├── User/                 # Citizen Mobile App (Expo/React Native)
│   ├── src/
│   └── android/
├── Frontend/             # Admin & Worker Portals (Next.js 16)
│   ├── app/
│   └── components/
└── static/               # Static page for pipeline preview

Tech Stack

Getting Started

Prerequisites

• Node.js 20+
• Python 3.11+
• Docker & Docker Compose
• PostgreSQL 15+
• Android SDK (for mobile development)

Installation

# Clone the repository
git clone https://github.com/0xarchit/CityTrack.git
cd CityTrack

# Backend Setup
cd Backend
pip install -r requirements.txt

# Frontend Setup
cd ../Frontend
npm install

# Mobile App Setup
cd ../User
npm install

Environment Configuration

Backend/.env

DATABASE_URL=postgresql://user:password@localhost:5432/citytrack
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_service_role_key
SUPABASE_BUCKET=your_bucket_name
SUPABASE_JWT_SECRET=your_jwt_secret
GOOGLE_CLIENT_ID=your_google_client_id
GEMINI_API_KEY=your_gemini_api_key
SENDER_EMAIL=noreply@yourdomain.com
RESEND_API_KEY=your_resend_api_key

Frontend/.env.local

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

User/.env

EXPO_PUBLIC_API_BASE_URL=http://localhost:8000
EXPO_PUBLIC_SUPABASE_URL=your_supabase_url
EXPO_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
EXPO_PUBLIC_GOOGLE_CLIENT_ID=your_google_client_id

Running the Project

Using Docker (Recommended):

docker compose up

Manual Setup:

# Terminal 1 - Backend
cd Backend
uvicorn api.app:app --host 0.0.0.0 --port 8000 --reload

# Terminal 2 - Frontend
cd Frontend
npm run dev

# Terminal 3 - Mobile App
cd User
npm start

Components

• agents/: 7 Autonomous Agents (Vision, GeoDeduplicate, Priority, Routing, SLA, Escalation, Notification)
• api/: Stateless REST Endpoints for Admin, Worker, and Issue routes
• core/: Configuration, Event Bus, Flow Tracker, Pydantic Models
• database/: SQLAlchemy Models, Connection Pool, SQL Migrations
• services/: Email, Geocoding, and Vision Processing services

Key Features

Admin Features

• Geospatial Heatmaps: Visual density plots for problem areas
• Department Management: Create and manage city departments
• Worker Administration: Onboard and assign workers
• Manual Review Queue: Review AI decisions
• Analytics Dashboard: Real-time metrics and trends

Worker Features

• Priority Task List: Auto-sorted by urgency and proximity
• One-Tap Navigation: Google Maps integration
• Evidence Upload: Mandatory before-and-after photos
• Task History: Complete audit trail

Deployment

Docker Deployment

# Build and run with Docker Compose
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

GitHub Actions CI/CD

Automated workflows for Docker image building, pushing to GHCR, and deployment.

Roadmap

Phase 1: Foundation (Completed)

• Autonomous Agent Pipeline
• Cross-Platform Ecosystem
• Real-time notifications and tracking
• Anti-fraud mechanisms

Phase 2: Intelligence Enhancement (In Progress)

• Predictive Maintenance using historical data
• Automated Testing suite
• Multi-City Support with tenant architecture
• Civic Reputation System

Phase 3: Scale & Gamification (Planned)

• Advanced Analytics with ML models
• Incentive Programs (tax credits, transit passes)
• Public API for third-party integrations
• Mobile SDK for white-label solutions
• IoT Integration (smart bins, streetlights, sensors)

Contributing

We welcome contributions!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 for Python code
• Use TypeScript for all new frontend code
• Write descriptive commit messages
• Add tests for new features
• Update documentation as needed

Team

Built by BitBots at IIIT Una, HackTheThrone 2026

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• YOLOv8 by Ultralytics for object detection
• Supabase for authentication and storage
• FastAPI for the robust backend framework
• Next.js and React Native teams for excellent frameworks