Update README.md

README.md

@@ -1,10 +1,146 @@
+# 📘 Cover Validation API
+
+Automated quality and layout validator for book covers.  
+Detects text overlaps, spacing issues, image quality problems, and manages workflow integration with Airtable, Google Drive, and Make automation.
+
+---
+
+## 🚀 Overview
+
+This FastAPI-based service processes book cover images or PDFs and validates layout rules automatically.  
+It aims to reduce manual QA time by 80% while maintaining 90%+ detection accuracy.
+
+**Core validations include:**
+- Author name overlapping with the *21st Century Emily Dickinson Award* badge zone.  
+- Text within unsafe margins (3 mm on sides, 9 mm bottom reserved area).  
+- Missing or unauthorized text in the award zone.  
+- Image sharpness, resolution, and alignment.
+
+---
+
+## ⚙️ Technical Stack
+
+| Component | Purpose |
+|------------|----------|
+| **FastAPI** | Core REST API |
+| **EasyOCR + OpenCV** | Text and layout detection |
+| **PyAirtable** | Database integration |
+| **Make (Integromat)** | Workflow automation |
+| **Google Drive** | File upload trigger |
+| **Hugging Face Spaces (Docker)** | Deployment environment |
+
+---
+
+## 🧠 API Endpoints
+
+### `POST /analyze`
+Uploads and validates a single cover file.
+
+**Request**
+- `multipart/form-data`
+- field: `file` → PNG or PDF file
+
+**Response**
+```json
+{
+  "isbn": "1234567890123",
+  "status": "PASS",
+  "confidence": 92.3,
+  "validation_message": "Image resolution and layout OK",
+  "airtable_record_id": "recXXXX"
+}
+```
+
+**Status logic**
+- ✅ **PASS** – all layout and quality rules met  
+- ⚠️ **REVIEW NEEDED** – minor overlap, low resolution, or OCR uncertainty
+
 ---
-title: Cover Overlap Detection
-emoji: 🌍
-colorFrom: gray
-colorTo: gray
-sdk: docker
-pinned: false
+
+## 🧩 Automation Workflow
+
+**Trigger:**  
+Book cover uploaded to a Google Drive folder.
+
+**Pipeline:**  
+1. Google Drive → Watch Files in Folder  
+2. Download file  
+3. HTTP → POST to this API (`/analyze`)  
+4. Parse JSON response  
+5. Gmail → Send formatted report to author  
+6. (Optional) Airtable → Log record update
+
+All modules run inside one **Make.com scenario** for full automation.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## ✉️ Email Template
+
+```
+Subject:  Cover Validation: {{status}}
+
+Dear Author,
+
+Your book cover has been reviewed by the automated validation system.
+
+Status: {{status}}
+Confidence: {{confidence}}%
+Issues: {{issues}}
+
+{{overlay_url}}
+
+If status is "REVIEW NEEDED", please make the suggested corrections and re-upload your file.
+
+–  Validation Team
+```
+
+---
+
+## 🧾 Airtable Fields
+
+| Field | Description |
+|--------|--------------|
+| Book ID (ISBN) | Extracted from filename |
+| Detection Timestamp | UTC time of validation |
+| Issue Type | Badge Overlap / Safe Margin / Quality |
+| Status | PASS / REVIEW NEEDED |
+| Confidence | 0–100% combined OCR + overlap score |
+| Overlay URL | Annotated image |
+| Correction Notes | Auto-generated text |
+| Author Email | For notification mapping |
+
+---
+
+## 🧪 Local Development
+
+```bash
+pip install -r requirements.txt
+uvicorn main:app --reload
+```
+
+Access Swagger UI at:  
+[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
+
+---
+
+## ☁️ Deployment (Hugging Face Spaces)
+
+Uses **Docker SDK**:
+```dockerfile
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+Environment variables (`Settings → Variables and secrets`):
+```
+AIRTABLE_BASE=appXXXX
+AIRTABLE_TABLE=Book cover revision
+AIRTABLE_KEY=keyXXXX
+MAKE_WEBHOOK=https://hook.eu1.make.com/abcd1234efgh5678
+```
+
+---
+
+## 🔒 Notes
+
+- SMTP ports are blocked on Spaces → all emails sent through Make webhook.  
+- Use HTTPS APIs only for outbound requests.  
+- Models load once at startup for faster inference.