metadata
title: CityTrack
emoji: 🏙️
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: true
CityTrack
______ _ _ _______ _
/ _____(_) | |__ __| | |
| | _| |_ _ _ | |_ __ __ _ ___ | | _____ _ __
| | | | __| | | | | | '__/ _` |/ __|| |/ / _ \ '__|
| |_____ | | |_| |_| | | | | | (_| | (__ | < __/ |
\______||_|\__|\__, | |_|_| \__,_|\___||_|\_\___|_|
_/ |
|___/
"Governance at the Speed of Software."
❏ Overview
CityTrack is an autonomous, event-driven operating system for smart cities that transforms civil infrastructure maintenance from reactive to proactive. Unlike traditional 311 systems that rely on manual triage, CityTrack leverages AI agents to instantly detect, validate, and route urban issues - such as potholes, illegal dumping, and damaged signage - without human fatigue or bias. By using citizens as real-time sensors and autonomous agents as the nervous system, CityTrack ensures city-scale, self-healing infrastructure.
❏ System Internals: The "Issue Packet"
Every interaction in CityTrack starts with an Issue Packet - an immutable, atomic unit of civic data.
Components:
- Evidence: Primary visual proof (Image/Video) captured via mandatory live camera
- Context: High-precision GPS (less than 10m accuracy), Compass Heading, and Device Metadata
- Intent: User-provided description, enhanced by NLP
Anti-Fraud Enforcement
CityTrack implements a "Spot-Check" protocol to ensure data integrity at the source:
- Live Camera Only: The mobile app restricts gallery access. Users MUST capture photos live, preventing the repurposing of old or internet images.
- GPS Precision Lock: Submission is blocked unless GPS accuracy is better than 10 meters.
- Identity Binding: All reports are cryptographically linked to a verified Google Identity (Supabase Auth).
❏ The Problem
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 and wasting resources
- Data Black Holes: Citizens rarely receive feedback on their reports, leading to civic frustration
- Subjective Prioritization: Urgent issues on main roads are often treated the same as minor issues in quiet alleys
❏ The Solution: CityTrack
CityTrack introduces the "Issue Packet" - an immutable unit of data containing visual evidence, GPS metadata, and intent. This packet triggers an autonomous chain reaction across a specialized agent pipeline.
System Architecture
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
❏ The Autonomous Pipeline
The system acts as a nervous system where agents react to the "Issue Packet" in real-time.
Stage 1: The Senses (Input & Validation)
Vision Agent: The "Eyes"
- Uses a fine-tuned YOLOv8s model to scan incoming images
- Rejection: Automatically discards irrelevant images (e.g., selfies, blurry photos)
- Classification: Identifies defects (Pothole, Debris, Graffiti) with confidence scores
Geo-Temporal Deduplication Agent: The "Memory"
- Clustering: Uses bounding box queries and haversine distance calculation to find similar reports within X meters and Y hours
- Merging: Instead of creating duplicates, it merges reports into a single "Cluster", increasing its urgency score
Stage 2: The Brain (Decision Making)
Priority Agent: The "Judge"
- Context Awareness: Combines Vision Confidence + Location Context (e.g., "Near School") + Repeat Count
- SLA Setting: Assigns dynamic deadlines (e.g., 4 hours for Critical)
Routing Agent: The "Dispatcher"
- Logic: Matches issue category to Department (Roads vs Sanitation) and assigns to specific workers based on geolocation and load
Stage 3: The Enforcers (Execution)
SLA Watchdog Agent: The "Timekeeper"
- AI Monitoring: Analyzes the context of delayed issues, not just the timer
- Escalation: Triggers warnings at 50% and 20% remaining time
Notification Agent: The "Messenger"
- Omnichannel: Pushes updates to the Citizen (App) and Worker (Task List) simultaneously
- Email Notifications: Sends email notifications to respective stakeholders
❏ Client Ecosystem
1. Citizen Mobile App (The Sensors)
Built with React Native + Expo (TypeScript)
- Offline-First: Caches reports locally and syncs when connection returns (Beta)
- Real-Time Tracking: Server-driven events update the "Processing" screen live as agents complete their tasks
- 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: System configuration
- Department Admin: Department-level oversight
- Worker Dashboard: Task submission and resolution
- Visual Intelligence: Heatmaps and density plots to identify crumbling infrastructure zones
3. Worker Interface (The Hands)
Mobile-First Web View
- Task List: Simple, priority-sorted list of jobs
- Navigation: One-tap deep link to Google Maps
- Proof of Resolution: Workers cannot close a ticket without uploading a photo. The Vision Agent verifies this photo against the original to confirm the fix.
❏ Technical Architecture
Modular Monolith Structure
The codebase is structured to scale from a Monolith to Microservices easily.
/
├── Backend/ # The Core Logic (FastAPI + Async SQLAlchemy)
│ ├── agents/ # The Brain: 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
│ │ └── routes/ # Admin, Worker, Issue Routes
│ ├── core/ # Shared Infrastructure
│ │ ├── config.py # Configuration Management
│ │ ├── events.py # Event Bus System
│ │ ├── flow_tracker.py # Pipeline Orchestration
│ │ └── schemas.py # Pydantic Models
│ ├── database/ # Database Layer
│ │ ├── models.py # SQLAlchemy Models
│ │ ├── connection.py # DB Connection Pool
│ │ └── migrations/ # SQL Migrations
│ ├── orchestration/ # Agent Base Classes & Workflow Managers
│ └── services/ # External Services
│ ├── email.py # Email Service
│ ├── geocoding.py # Geocoding Service
│ └── vision.py # Vision Processing
├── User/ # Citizen Mobile App (Expo/React Native)
│ ├── src/
│ │ ├── screens/ # App Screens
│ │ ├── components/ # Reusable Components
│ │ ├── services/ # API Services
│ │ └── navigation/ # Navigation Setup
│ └── android/ # Android Build Configuration
├── Frontend/ # Admin & Worker Portals (Next.js 16)
│ ├── app/ # App Router Pages
│ │ ├── admin/ # Admin Dashboard
│ │ ├── worker/ # Worker Dashboard
│ │ └── user/ # Citizen Portal
│ └── components/ # Shared Components
└── static/ # Static page for agentic pipeline preview
└── requestly/ # Requestly export file for requestly api testing
❏ Technology Stack
Backend
- Framework: FastAPI (Python 3.11+)
- ORM: SQLAlchemy 2.0 (Async)
- Database: PostgreSQL 18
- Geospatial: Haversine distance calculation for coordinate-based queries
- Task Queue: Background tasks with FastAPI BackgroundTasks
- Authentication: Supabase Auth
AI/ML
- Vision Model: YOLOv8s (Fine-tuned for urban defects)
- Training: Custom dataset of 2000+ labeled urban issue images
- Inference: Real-time on CPU with optimized preprocessing
Frontend
- Web Framework: Next.js 16 (App Router)
- Styling: Tailwind CSS
- State Management: React Hooks + Context API
- Data Fetching: Native Fetch API with caching
Mobile
- Framework: React Native with Expo SDK 54
- Language: TypeScript
- Navigation: React Navigation
- Storage: Async Storage + Expo Secure Store
Infrastructure
- Authentication: Supabase Auth (Google OAuth)
- Storage: Supabase Storage (Image uploads)
- Deployment: Docker + Docker Compose
- CI/CD: GitHub Actions
- Container Registry: GitHub Container Registry (GHCR)
❏ 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
Create .env files in respective directories:
Backend/.env
# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/citytrack
# Supabase Configuration
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_service_role_key
SUPABASE_BUCKET=your_bucket_name
SUPABASE_JWT_SECRET=your_jwt_secret
# Supabase S3 Storage Configuration
SUPABASE_S3_ENDPOINT=your_s3_endpoint
SUPABASE_S3_REGION=your_s3_region
SUPABASE_S3_ACCESS_KEY=your_s3_access_key
SUPABASE_S3_SECRET_KEY=your_s3_secret_key
# Google OAuth Configuration
GOOGLE_CLIENT_ID=your_google_client_id
PROJECT_ID=your_google_project_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
# Email Configuration
SENDER_EMAIL=noreply@yourdomain.com
ADMIN_EMAIL=admin@yourdomain.com
RESEND_API_KEY=your_resend_api_key
# AI/ML Configuration
GEMINI_API_KEY=your_gemini_api_key
Frontend/.env.local
# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
User/.env
# API Configuration
EXPO_PUBLIC_API_BASE_URL=http://localhost:8000
# Supabase Configuration
EXPO_PUBLIC_SUPABASE_URL=your_supabase_url
EXPO_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
# Google OAuth Configuration
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
Building for Production
Backend Docker Image:
docker build -t citytrack-backend .
Frontend:
cd Frontend
npm run build
npm start
Mobile App (Android):
cd User/android
./gradlew assembleRelease
❏ Key Features
Core Functionality
- ❏ Anti-Fraud Reporting: Mandatory live camera and high-precision GPS lock to prevent fake reports
- ❏ AI-Powered Validation: Automatic classification and spam detection 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
Admin Features
- ❏ Geospatial Heatmaps: Visual density plots to identify problem areas
- ❏ Department Management: Create and manage city departments
- ❏ Worker Administration: Onboard and assign workers to departments
- ❏ Manual Review Queue: Review AI decisions and provide feedback
- ❏ Analytics Dashboard: Real-time metrics and historical trends
Worker Features
- ❏ Priority Task List: Auto-sorted by urgency and proximity
- ❏ One-Tap Navigation: Direct integration with Google Maps
- ❏ Evidence Upload: Mandatory before-and-after photo comparison
- ❏ Task History: Complete audit trail of resolved issues
❏ Agent Pipeline Details
Input & Validation Layer
Vision Agent
- Scans images using fine-tuned YOLOv8 model
- Detects objects: potholes, garbage, debris, damaged infrastructure
- Rejects spam: selfies, irrelevant content, low-quality images
- Classifies issues with confidence scores
- Annotates images with bounding boxes
Geo-Temporal Deduplication Agent
- Uses bounding box queries on indexed latitude/longitude columns
- Applies haversine distance calculation to find nearby reports
- Checks for duplicates within configurable radius and time window
- Merges duplicate reports into clusters
- Increases urgency score for repeated reports
- Maintains report history and relationships
Decision Making Layer
Priority Agent
- Assigns severity levels: CRITICAL, HIGH, MEDIUM, LOW
- Considers multiple factors:
- AI confidence score
- Location context (near schools, hospitals, main roads)
- Report clustering (multiple reports = higher priority)
- Historical data (recurring issues in same location)
- Sets dynamic SLA deadlines based on severity
- Provides justification for priority assignment
Routing Agent
- Matches issue category to correct department
- Selects optimal worker based on:
- Geographic proximity
- Current workload
- Specialization
- Availability
- Balances resource allocation across the city
- Handles department-specific routing rules
Execution & Follow-up Layer
SLA Watchdog Agent
- Monitors all active issues against SLA deadlines
- Triggers warnings at 50% and 20% remaining time
- Analyzes context of delays (holidays, weather, resource constraints)
- Provides early warning system for potential SLA breaches
Escalation Agent
- Handles overdue issues automatically
- Reassigns to supervisors or alternate workers
- Increases issue priority
- Flags for administrative review
- Maintains transparency in escalation chain
Notification Agent
- Sends real-time updates via multiple channels:
- In-app push notifications
- Email notifications
- SMS (planned)
- Notifies citizens of status changes
- Alerts workers of new assignments
- Informs admins of escalations
- Supports templated messages with dynamic content
❏ Deployment
Docker Deployment
The project includes a complete Docker setup for production 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 and pushing to GHCR
- Deployment to production (completed)
- Automated testing (planned)
❏ Roadmap & Future Vision
Phase 1: The Foundation (Completed)
- ❏ Autonomous Agent Pipeline (Vision, Geo, Priority, Routing, etc.)
- ❏ Cross-Platform Ecosystem (Citizen App, Admin Portal, Worker View)
- ❏ Real-time notifications and tracking
- ❏ Anti-fraud mechanisms
Phase 2: Intelligence Enhancement (In Progress)
- ❏ Predictive Maintenance: Using historical data to predict infrastructure failures
- ❏ Automated Testing: Comprehensive test suite
- ❏ Multi-City Support: Tenant-based architecture
- ❏ Civic Reputation System: Leaderboards for top contributors
Phase 3: Scale & Gamification (Planned)
- ❏ Advanced Analytics: ML models for pattern recognition
- ❏ Incentive Programs: Tax credits or transit passes for verified reporting
- ❏ Public API: Third-party integrations
- ❏ Mobile SDK: White-label solution for other cities
- ❏ IoT Integration: Direct feeds from smart bins, streetlights, and sensors
❏ Contributing
We welcome contributions! Please read our contributing guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - 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
| Role | Name | GitHub |
|---|---|---|
| Lead Developer | Archit Jain | @0xarchit |
| Developer | Rachit Verma | @vxrachit |
| Developer | Pushpendra Sharma | @synapticpush |
| Developer | Deepti Yadav | @DeeptiYadav10648 |
❏ 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
CityTrack - Transforming urban governance through autonomous AI agents.