feat: offload event deletion to asynchronous celery task & update docs

- Refactored `DeleteEventTableUseCase` to trigger a background Celery task (`delete_event_data_task`) rather than blocking the HTTP response, preventing frontend serverless timeouts.
- Added `event_id` parameter to the `DELETE /api/events/delete-event-table/{event_code}` endpoint to allow the backend to clean up associated zip directories.
- Implemented `delete_folder` in the MinIO storage adapter using `list_objects_v2` pagination to recursively wipe S3 directories.
- Updated `ITaskQueueService` and `IStorageService` ports to reflect new deletion capabilities.
- Wired the new queue dependency to the deletion use case in `di_container.py`.
- docs: Completely overhauled `README.md`, `main_api/README.md`, `inference_api/README.md`, and `workflows.md` to reflect the GCP VM + PostgreSQL deployment (removing outdated mentions of Hugging Face, Redis, MinIO, and dynamic tables).
- docs: Added missing API schemas to `main_api/README.md` (Generate ZIP, Check ZIP, Delete Event Table) and fixed request payload typos.

Author: Avneesh11905

README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1>📸 Eventsnap API</h1>
   <i>A High-Performance Asynchronous Facial Recognition Pipeline</i><br>
-  <i>Powered by FastAPI, Celery, PostgreSQL pgvector, and Hugging Face</i>
+  <i>Powered by FastAPI, Celery, PostgreSQL pgvector, and ONNX Runtime</i>
 </div>
 
 ---
@@ -13,7 +13,7 @@ Eventsnap is a distributed, horizontally scalable microservice architecture desi
 It is split into two main components (each with their own dedicated README files):
 
 ### 1. `main_api` (The Orchestrator)
-A FastAPI server that acts as the entry point. It accepts requests, authenticates them, dynamically creates Postgres tables, and dumps background encoding tasks into RabbitMQ for Celery workers to pick up.
+A FastAPI server that acts as the entry point. It accepts requests, authenticates them, saves face embeddings to Postgres, and dumps background encoding tasks into RabbitMQ for Celery workers to pick up.
 
 ### 2. `inference_api` (The GPU Worker)
 A strictly mathematical, stateless ONNX Runtime container. It receives Base64 encoded photos, runs the powerful `insightface` SCRFD and ArcFace models on the NVIDIA GPU, and returns precise bounding boxes and 512-dimension `glintr100` embeddings.
@@ -25,9 +25,9 @@ A strictly mathematical, stateless ONNX Runtime container. It receives Base64 en
 *   **API Framework:** FastAPI (Python 3.14, Native AsyncIO)
 *   **Architecture Pattern:** Hexagonal Architecture (Ports and Adapters) with Dependency Injection
 *   **Package Manager:** uv (Ultra-fast Python package installer)
-*   **Background Tasks:** Celery + RabbitMQ (Broker) + Redis (Result Backend)
+*   **Background Tasks:** Celery + RabbitMQ (Broker) + PostgreSQL (Result Backend)
 *   **Database:** PostgreSQL + [`pgvector`](https://github.com/pgvector/pgvector) extension (Cosine Similarity matching)
-*   **Object Storage:** MinIO (S3 Compatible)
+*   **Object Storage:** Storage Bucket (S3 Compatible)
 *   **Machine Learning:** ONNX runtime (CUDA 11.8), InsightFace
 *   **Containerization:** Docker & Docker Compose
 
@@ -49,7 +49,7 @@ docker build -t main_api:dev ./main_api
 ```
 
 ### 2. Spin Up the Stack
-Bring up all the containers (Postgres DB, RabbitMQ, MinIO, Inference API, Main API, and Celery Worker). The orchestrated services will automatically wait for their database dependencies to become healthy before starting.
+Bring up all the containers (Postgres DB, RabbitMQ, Storage Bucket, Inference API, Main API, and Celery Worker). The orchestrated services will automatically wait for their database dependencies to become healthy before starting.
 
 ```bash
 docker compose up -d
@@ -65,8 +65,8 @@ docker compose up -d
 
 *(For detailed sequence diagrams of the complete asynchronous system, see [workflows.md](./workflows.md))*
 
-1.  A user uploads a ZIP of an event directly via the Next.js frontend, which extracts and pushes the images into **MinIO**.
+1.  A user uploads a ZIP of an event directly via the Next.js frontend, which extracts and pushes the images into **Storage Bucket**.
 2.  The frontend hits the **Main API** `/encode-event/` endpoint, passing the `event_code` in the JSON payload.
 3.  The **Main API** creates a Celery Task and immediately returns a `task_id` so the user isn't stuck waiting.
-4.  The background **Celery Worker** picks up the task, pre-fetches images from **MinIO** using an aggressive 64-connection pool, beams them (Base64) to the **Inference API**, and bulk-inserts the generated 512D vectors directly into **PostgreSQL**.
+4.  The background **Celery Worker** picks up the task, pre-fetches images from **Storage Bucket** using an aggressive 64-connection pool, beams them (Base64) to the **Inference API**, and bulk-inserts the generated 512D vectors directly into **PostgreSQL**.
 5.  An attendee hits the **Main API** `/sort-attendee/` endpoint with their selfies and the `event_code`. The orchestrator gets the embeddings for those selfies, averages them, and executes a sub-millisecond `<=>` cosine similarity search in `pgvector` to find all photos they appear in!

inference_api/README.md

@@ -2,7 +2,7 @@
 
 The `inference_api` is an ultra-fast, stateless FastAPI server designed purely for mathematical facial processing. It uses the `insightface` library powered by `onnxruntime-gpu` (CUDA 11) to extract 512-dimension vector embeddings from raw image data.
 
-It is designed to be horizontally scaled or deployed as a Serverless Endpoint on Hugging Face (e.g., Nvidia T4 hardware).
+It is designed to be horizontally scaled or deployed on a GCP VM (e.g., Nvidia T4 hardware).
 
 ## Core Responsibilities
 *   **Vectorization**: Converts human faces into mathematical matrices (ResNet100 model).

main_api/README.md

@@ -15,7 +15,7 @@ This API strictly follows the **Ports and Adapters (Hexagonal) Architecture** us
 
 *   **`domain/`**: Enterprise logic, entities, and domain exceptions. Completely independent of any external frameworks.
 *   **`application/`**: Business use cases (e.g., `events.py`, `attendees.py`, `background_tasks.py`), DTOs, and Ports (interfaces).
-*   **`infrastructure/`**: External adapters (Celery, PostgreSQL/pgvector, MinIO, HuggingFace Inference API, Image Augmentation).
+*   **`infrastructure/`**: External adapters (Celery, PostgreSQL/pgvector, Storage Bucket, Internal Inference API, Image Augmentation).
 *   **`presentation/`**: FastAPI routers, schemas, and exception handlers.
 
 ---
@@ -28,7 +28,7 @@ Content-Type: application/json
 ```
 
 ### 1. Encode Event (Asynchronous)
-Triggers the background Celery worker to download a folder from MinIO, process every image through the GPU inference API, and save the 512-dimension vector embeddings to Postgres.
+Triggers the background Celery worker to download a folder from Storage Bucket, process every image through the GPU inference API, and save the 512-dimension vector embeddings to Postgres.
 
 **Example `curl` Request:**
 ```bash
@@ -38,8 +38,8 @@ curl -X 'POST' \
   -d '{
   "event_code": "DCAYTI",
   "max_faces": 0,
-  "det_conf": 0.5,
-  "nms_thresh": 0.4
+  "detection_conf": 0.5,
+  "nms_threshold": 0.4
 }'
 ```
 
@@ -50,8 +50,8 @@ import axios from 'axios';
 const response = await axios.post('http://localhost:8000/api/events/encode-event/', {
   event_code: 'DCAYTI',
   max_faces: 0,
-  det_conf: 0.5,
-  nms_thresh: 0.4
+  detection_conf: 0.5,
+  nms_threshold: 0.4
 }, {
   headers: {
     'Content-Type': 'application/json'
@@ -200,6 +200,58 @@ console.log(response.data);
 }
 ```
 
+### 5. Generate ZIP
+Generates a ZIP archive containing the matched photos for an attendee.
+
+**Example Request:**
+```json
+{
+  "event_id": "uuid",
+  "user_id": "uuid",
+  "image_paths": [{}]
+}
+```
+**Response:**
+```json
+{
+  "success": true,
+  "task_id": "task-uuid",
+  "message": "message"
+}
+```
+
+### 6. Check ZIP Status
+Checks if a generated zip is available in the storage bucket.
+
+**Example Request:**
+```bash
+curl -X 'GET' 'http://localhost:8000/api/attendees/check-zip/{event_id}/{user_id}'
+```
+**Response:**
+```json
+{
+  "exists": true,
+  "zip_path": "zip/event_id/user_id.zip",
+  "filename": "user_id.zip"
+}
+```
+
+### 7. Delete Event Table
+Safely clears event table from DB and ML storage in the background.
+
+**Example Request:**
+```bash
+curl -X 'DELETE' 'http://localhost:8000/api/events/delete-event-table/{event_code}'
+```
+**Response:**
+```json
+{
+  "success": true,
+  "message": "message",
+  "table_name": "event_encodings"
+}
+```
+
 ## Running the Service
 The service is booted automatically via `docker-compose up`, but can be tested locally using:
 ```bash

main_api/application/ports/queue.py

@@ -32,3 +32,7 @@ def enqueue_create_zip(
     def get_task_status(self, task_id: str) -> Dict[str, Any]:
         """Returns dict with state, info, result"""
         pass
+
+    def enqueue_delete_event(self, event_code: str, event_id: str | None = None) -> str:
+        """Returns the task ID"""
+        pass

main_api/application/ports/storage.py

@@ -19,3 +19,6 @@ async def create_zip_from_images(
 
     async def check_zip_exists(self, zip_key: str) -> bool:
         pass
+
+    async def delete_folder(self, prefix: str) -> None:
+        pass

main_api/application/use_cases/events.py

@@ -41,14 +41,14 @@ async def execute(self, event_code: str) -> EncodedCountDTO:
 
 
 class DeleteEventTableUseCase:
-    def __init__(self, uow: IUnitOfWork):
-        self.uow = uow
+    def __init__(self, queue_service: ITaskQueueService):
+        self.queue_service = queue_service
 
-    async def execute(self, event_code: str) -> DeleteTableDTO:
-        async with self.uow as uow:
-            await uow.event_repo.delete_event_data(event_code)
-            await uow.commit()
+    async def execute(
+        self, event_code: str, event_id: str | None = None
+    ) -> DeleteTableDTO:
+        self.queue_service.enqueue_delete_event(event_code, event_id)
         return DeleteTableDTO(
             success=True,
-            message=f"Data for event '{event_code}' deleted successfully if it existed.",
+            message=f"Enqueued deletion task for event '{event_code}'.",
         )

main_api/infrastructure/di_container.py

@@ -84,7 +84,9 @@ class Container(containers.DeclarativeContainer):
 
     get_encoded_count_use_case = providers.Factory(GetEncodedCountUseCase, uow=uow)
 
-    delete_event_table_use_case = providers.Factory(DeleteEventTableUseCase, uow=uow)
+    delete_event_table_use_case = providers.Factory(
+        DeleteEventTableUseCase, queue_service=queue_service
+    )
 
     encode_attendee_use_case = providers.Factory(
         EncodeAttendeeUseCase,

main_api/infrastructure/queue/celery_service.py

@@ -42,6 +42,12 @@ def enqueue_create_zip(
         task = create_event_zip_task.delay(event_id, user_id, image_paths)
         return task.id
 
+    def enqueue_delete_event(self, event_code: str, event_id: str | None = None) -> str:
+        from infrastructure.queue.celery_workers import delete_event_data_task
+
+        task = delete_event_data_task.delay(event_code, event_id)
+        return task.id
+
     def get_task_status(self, task_id: str) -> Dict[str, Any]:
         res = AsyncResult(task_id, app=celery_app)
 

main_api/infrastructure/queue/celery_workers.py

@@ -88,3 +88,21 @@ def update_state_cb(state_name, meta_dict):
     if dataclasses.is_dataclass(result):
         return dataclasses.asdict(result)
     return result
+
+
+@shared_task(bind=True, name="delete_event_data_task", acks_late=True)
+def delete_event_data_task(self, event_code: str, event_id: str | None = None):
+    container = get_container()
+    uow = container.uow()
+    storage = container.storage_service()
+
+    async def _delete():
+        async with uow:
+            await uow.event_repo.delete_event_data(event_code)
+            await uow.commit()
+        await storage.delete_folder(f"event/{event_code}/")
+        if event_id:
+            await storage.delete_folder(f"zip/{event_id}/")
+
+    asyncio.run(_delete())
+    return {"success": True, "message": f"Deleted event {event_code}"}

main_api/infrastructure/storage/minio_service.py

@@ -142,3 +142,20 @@ async def check_zip_exists(self, zip_key: str) -> bool:
                 return True
             except Exception:
                 return False
+
+    async def delete_folder(self, prefix: str) -> None:
+        session = self._get_session()
+        async with session.client("s3", endpoint_url=self.endpoint_url) as s3:
+            paginator = s3.get_paginator("list_objects_v2")
+            async for page in paginator.paginate(
+                Bucket=self.bucket_name, Prefix=prefix
+            ):
+                if "Contents" in page:
+                    objects_to_delete = [
+                        {"Key": obj["Key"]} for obj in page["Contents"]
+                    ]
+                    if objects_to_delete:
+                        await s3.delete_objects(
+                            Bucket=self.bucket_name,
+                            Delete={"Objects": objects_to_delete, "Quiet": True},
+                        )