docs: comprehensive README with security features and architecture

README.md

@@ -11,4 +11,180 @@ pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🚗 Vehicle Intelligence System
+
+Advanced license plate detection, OCR, and natural language database querying system with security hardening.
+
+## 🎯 Features
+
+### Detection Pipeline
+- 🎥 **YOLO Plate Detection** - Real-time license plate localization
+- 🔤 **PaddleOCR** - High-accuracy OCR for plate text extraction
+- 🚗 **Vehicle Classification** - Classify vehicle types (car, truck, bike, etc.)
+- 🛡️ **Confidence Scoring** - All detections include confidence metrics
+
+### Database & Analytics
+- 📊 **Supabase PostgreSQL** - Robust cloud database with automatic backups
+- 🔍 **NLP-to-SQL** - Ask questions in natural language, AI converts to SQL
+- 🛡️ **SQL Validation** - Prevents injection attacks and dangerous queries
+- ⚡ **Optimized Indexes** - Fast queries with proper database indexing
+- 📈 **Real-time Analytics** - Dashboard with state distribution, hourly traffic, suspicious vehicles
+
+### Security Features
+- ✅ **SQL Injection Prevention** - Whitelist/blacklist keyword validation
+- 🔒 **Read-Only Queries** - Only SELECT queries allowed
+- 📝 **Query History** - Track all database queries for audit
+- 🔐 **State Extraction** - Automatically extract state codes from license plates
+
+## 📂 Modular Architecture
+
+```
+plate-detector/
+├── app.py              # Main Gradio UI with 3 tabs
+├── detector.py         # YOLO, OCR, vehicle classification
+├── database.py         # SQL validation, LLM, database operations
+├── requirements.txt    # Python dependencies
+└── .env               # Environment variables (Supabase, HF token)
+```
+
+### Files Explained
+
+**app.py** - Simplified UI layer
+- Detection tab: Upload images, detect plates
+- Database Query tab: NLP-to-SQL search with example queries
+- Analytics tab: Real-time dashboard with metrics
+
+**detector.py** - Computer Vision Module
+- License plate detection using YOLO
+- OCR using PaddleOCR
+- Vehicle classification (10 types)
+- State code extraction (TN, KA, KL, etc.)
+- Image preprocessing and augmentation
+
+**database.py** - Data & Security Layer
+- SQL validation (blocks DELETE, UPDATE, INSERT, DROP)
+- SQLCoder LLM integration for NLP-to-SQL
+- Database initialization with improved schema
+- Automatic index creation for performance
+- Query history tracking
+- Analytics functions (suspicious vehicles, hourly traffic, etc.)
+
+## 🚀 Deployment
+
+### Environment Variables
+
+Create `.env` file with:
+
+```
+DATABASE_URL=postgresql://user:password@host:5432/postgres
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### Run Locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+Visit: http://localhost:7860
+
+### Deploy on Hugging Face Spaces
+
+1. Push code to HF Spaces repository
+2. Add secrets in Settings:
+   - `DATABASE_URL` - Supabase connection string
+   - `HF_TOKEN` - Hugging Face API token
+
+## 🛡️ Security Measures
+
+### SQL Validation
+
+```python
+ALLOWED_KEYWORDS = ["SELECT", "FROM", "WHERE", "COUNT", ...]
+BLOCKED_KEYWORDS = ["DROP", "DELETE", "UPDATE", "INSERT", ...]
+
+# Only SELECT queries allowed
+# Blocks all dangerous operations
+```
+
+### Database Schema
+
+```sql
+CREATE TABLE vehicle_logs (
+    id BIGSERIAL PRIMARY KEY,
+    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    plate TEXT,
+    state TEXT,
+    vehicle_type TEXT,
+    vehicle_conf FLOAT,
+    camera_id TEXT,
+    location TEXT,
+    image_url TEXT,
+    date DATE,
+    hour INTEGER,
+    day TEXT
+);
+```
+
+### Indexes for Performance
+
+```sql
+CREATE INDEX idx_plate ON vehicle_logs(plate);
+CREATE INDEX idx_state ON vehicle_logs(state);
+CREATE INDEX idx_vehicle_type ON vehicle_logs(vehicle_type);
+CREATE INDEX idx_timestamp ON vehicle_logs(timestamp);
+CREATE INDEX idx_date ON vehicle_logs(date);
+```
+
+## 🎯 Example Queries
+
+- "How many cars today?"
+- "Show all trucks"
+- "Count bikes"
+- "Show TN vehicles"
+- "Show vehicles after 6pm"
+- "List latest 10 detections"
+- "Count vehicles by type"
+- "Show high confidence detections"
+- "List all unique plates"
+- "Show suspicious vehicles"
+
+## 📊 Analytics Dashboard
+
+- **Vehicles by State** - Distribution of detections across states
+- **Traffic by Hour** - Hourly traffic patterns
+- **Top Plates** - Most frequently detected license plates
+- **Suspicious Vehicles** - High-frequency detections (>20 times)
+
+## 🔮 Future Improvements
+
+- [ ] Vector search for similar plates
+- [ ] Async database queries for better performance
+- [ ] Image storage and retrieval
+- [ ] Camera tracking and geolocation
+- [ ] Result caching with Redis
+- [ ] FastAPI backend separation
+- [ ] React dashboard frontend
+
+## 📦 Dependencies
+
+- ultralytics - YOLO detection
+- paddleocr - OCR
+- transformers - Vehicle classification
+- sqlalchemy - Database ORM
+- huggingface-hub - LLM inference
+- gradio - Web UI
+- opencv - Image processing
+
+## 📄 License
+
+MIT License - See LICENSE file
+
+## 🤝 Contributing
+
+Contributions welcome! Please submit pull requests or issues.
+
+---
+
+**Live Demo:** https://huggingface.co/spaces/BARATH0070/plate-detector