refactor readme.md

.github/workflows/docker-publish.yml

@@ -55,7 +55,7 @@ jobs:
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
-            type=sha,prefix={{branch}}-
+            type=sha,prefix=sha-
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Build and push Docker image

README.md

@@ -1,8 +1,8 @@
 ---
-title: citytrack
-emoji: 🌆
-colorFrom: green
-colorTo: blue
+title: CityTrack
+emoji: 🏙️
+colorFrom: blue
+colorTo: green
 sdk: docker
 app_port: 7860
 pinned: true
@@ -10,76 +10,517 @@ pinned: true
 
 # CityTrack
 
-> **Governance at the Speed of Software**
+```text
+   ______ _ _            _______              _             
+  / _____(_) |         |__   __|            | |            
+ | |       _| |_ _   _    | |_ __ __ _  ___ | | _____ _ __ 
+ | |      | | __| | | |   | | '__/ _` |/ __|| |/ / _ \ '__|
+ | |_____ | | |_| |_| |   | | | | (_| | (__ |   <  __/ |   
+  \______||_|\__|\__, |   |_|_|  \__,_|\___||_|\_\___|_|   
+                   _/ |                                    
+                  |___/                                     
+```
+
+<div align="center">
+
+![Repo Size](https://img.shields.io/github/repo-size/0xarchit/CityTrack?style=for-the-badge&color=2ecc71)
+![Last Commit](https://img.shields.io/github/last-commit/0xarchit/CityTrack?style=for-the-badge&color=3498db)  
+![Issues](https://img.shields.io/github/issues/0xarchit/CityTrack?style=for-the-badge&color=e74c3c)
+![Pull Requests](https://img.shields.io/github/issues-pr/0xarchit/CityTrack?style=for-the-badge&color=9b59b6)
+
+</div>
+
+**"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:
+
+1. **Live Camera Only:** The mobile app restricts gallery access. Users MUST capture photos live, preventing the repurposing of old or internet images.
+2. **GPS Precision Lock:** Submission is blocked unless GPS accuracy is better than 10 meters.
+3. **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
+
+```mermaid
+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)
 
-CityTrack is an AI-powered urban issue reporting and management platform that transforms how cities handle infrastructure problems. Citizens report issues with AI validation, and autonomous agents route them to the right departments in real-time.
+**Routing Agent: The "Dispatcher"**
+- **Logic:** Matches issue category to Department (Roads vs Sanitation) and assigns to specific workers based on geolocation and load
 
-## Quick Overview
+### Stage 3: The Enforcers (Execution)
 
-**The Problem:** Traditional city issue reporting systems are slow, manual, and prone to duplicates.
+**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
 
-**The Solution:** CityTrack uses AI agents to instantly validate, deduplicate, and intelligently route urban issues—turning citizens into real-time sensors for city infrastructure.
+**Notification Agent: The "Messenger"**
+- **Omnichannel:** Pushes updates to the Citizen (App) and Worker (Task List) simultaneously
+- **Email Notifications:** Sends email notifications to respective stakeholders
 
-## Key Features (MVP)
+## ❏ Client Ecosystem
 
-- 📸 **Live Camera Capture:** Mandatory camera verification to prevent fake reports
-- 📍 **GPS Validation:** High-precision location data (< 10m accuracy)
-- 🤖 **AI Issue Classification:** Automatic detection of potholes, debris, and damaged infrastructure
-- 🔄 **Smart Deduplication:** Groups similar reports and prevents redundant tickets
-- 👷 **Worker Dashboard:** Task list with instant notifications and routing
-- 📱 **Citizen Tracking:** Real-time updates on report status
+### 1. Citizen Mobile App (The Sensors)
+*Built with React Native + Expo (TypeScript)*
 
-## Getting Started
+- **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.
+
+```text
+/
+├── 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 with PostGIS extension
+- PostgreSQL 15+
+- Android SDK (for mobile development)
 
 ### Installation
 
 ```bash
+# Clone the repository
 git clone https://github.com/0xarchit/CityTrack.git
 cd CityTrack
 
-docker-compose up -d
+# Backend Setup
+cd Backend
+pip install -r requirements.txt
 
+# Frontend Setup
+cd ../Frontend
 npm install
-pip install -r requirements.txt
+
+# Mobile App Setup
+cd ../User
+npm install
+```
+
+### Environment Configuration
+
+Create `.env` files in respective directories:
+
+**Backend/.env**
+```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**
+```env
+# 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**
+```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):**
+```bash
+docker compose up
+```
+
+**Manual Setup:**
+```bash
+# 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:**
+```bash
+docker build -t citytrack-backend .
+```
+
+**Frontend:**
+```bash
+cd Frontend
+npm run build
+npm start
+```
+
+**Mobile App (Android):**
+```bash
+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:
+
 ```bash
-docker-compose up
+# Build and run with Docker Compose
+docker compose up -d
+
+# View logs
+docker compose logs -f
 
-npm run dev         # Frontend
-python main.py      # Backend
+# Stop services
+docker compose down
 ```
 
-## Tech Stack
+### 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
 
-- **Backend:** FastAPI, Python, SQLAlchemy, PostgreSQL
-- **Frontend:** Next.js, Tailwind CSS
-- **Mobile:** React Native, Expo
-- **AI/ML:** YOLOv8 (Issue Detection)
-- **Authentication:** Supabase
-- **Infrastructure:** Docker
+### 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
 
-## The Autonomous Pipeline
+### 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
 
-1. **Vision Agent** → Validates and classifies uploaded images
-2. **Geo-Dedup Agent** → Merges duplicate reports in the same area
-3. **Priority Agent** → Assigns urgency levels based on context
-4. **Routing Agent** → Matches issues to departments and workers
-5. **Notification Agent** → Sends updates to all stakeholders
+## ❏ Contributing
 
-## Contributing
+We welcome contributions! Please read our contributing guidelines:
 
-We welcome contributions! Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+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
 
-## Team
+### 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
 
@@ -90,6 +531,17 @@ Built by **BitBots** at IIIT Una, HackTheThrone 2026
 | Developer | Pushpendra Sharma | [@synapticpush](https://github.com/synapticpush) |
 | Developer | Deepti Yadav | [@DeeptiYadav10648](https://github.com/DeeptiYadav10648) |
 
-## License
+## ❏ License
+
+This project is licensed under the MIT License - see the [LICENSE](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
+
+---
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+**CityTrack** - Transforming urban governance through autonomous AI agents.