Merge pull request #64 from ClipABit/split-backend

CLI-45: Split backend into 3 apps

Author: eshaan-mehta

.github/workflows/cd.yml

@@ -12,6 +12,10 @@ concurrency:
 permissions:
   contents: write
 
+# Note: We deploy the individual apps (server.py, search_app.py, processing_app.py)
+# for optimal cold start performance. The dev_combined.py app is ONLY for local
+# development and should never be deployed to staging/prod.
+
 jobs:
   # ------------------------------------------------------------------
   # STAGING DEPLOYMENT (Runs on push to 'staging')
@@ -38,15 +42,29 @@ jobs:
       - name: Install dependencies
         run: uv sync --frozen
 
-      - name: Deploy to Modal (Staging)
+      - name: Deploy Processing App (Staging)
+        env:
+          MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+          MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+          ENVIRONMENT: staging
+        run: uv run modal deploy apps/processing_app.py
+
+      - name: Deploy Search App (Staging)
         env:
           MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
           MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
-          ENVIRONMENT: staging # for OS
-        run: uv run modal deploy main.py
+          ENVIRONMENT: staging
+        run: uv run modal deploy apps/search_app.py
+
+      - name: Deploy Server (Staging)
+        env:
+          MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+          MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+          ENVIRONMENT: staging
+        run: uv run modal deploy apps/server.py
 
   # ------------------------------------------------------------------
-  # PRODUCTION DEPLOYMENT (Runs only when manually triggered)
+  # PRODUCTION DEPLOYMENT (Runs on push to 'main')
   # ------------------------------------------------------------------
   deploy-prod:
     name: Deploy Production
@@ -69,9 +87,23 @@ jobs:
       - name: Install dependencies
         run: uv sync --frozen
 
-      - name: Deploy to Modal (Prod)
+      - name: Deploy Processing App (Prod)
+        env:
+          MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+          MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+          ENVIRONMENT: prod
+        run: uv run modal deploy apps/processing_app.py
+
+      - name: Deploy Search App (Prod)
+        env:
+          MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+          MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+          ENVIRONMENT: prod
+        run: uv run modal deploy apps/search_app.py
+
+      - name: Deploy Server (Prod)
         env:
           MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
           MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
           ENVIRONMENT: prod
-        run: uv run modal deploy main.py
+        run: uv run modal deploy apps/server.py

backend/README.md

@@ -1,6 +1,31 @@
 # ClipABit Backend
 
-Video processing backend that runs on Modal. Accepts video uploads via FastAPI and processes them in serverless containers.
+Video processing backend that runs on Modal. Built as a microservices architecture with three specialized apps for optimized cold start times.
+
+## Architecture
+
+The backend uses different architectures for development vs production:
+
+### Production (staging/prod)
+
+Split into three Modal apps for optimal cold start times:
+
+| App | Purpose | Dependencies |
+|-----|---------|--------------|
+| **server** | API gateway, handles requests, lightweight operations | Minimal (FastAPI, boto3) |
+| **search** | Semantic search with CLIP text encoder | Medium (torch, transformers) |
+| **processing** | Video processing, embedding generation | Heavy (ffmpeg, opencv, torch, transformers) |
+
+This architecture ensures that lightweight API calls (health, status, list) don't need to load heavy ML models.
+
+### Local Development (dev)
+
+Single combined Modal app (`dev_combined.py`) with all three services:
+
+| App | Purpose |
+|-----|---------|
+| **dev-combined** | Server + Search + Processing in one app |
+This allows hot-reload on all services without cross-app lookup issues. Cold start time is acceptable for local development where iteration speed matters more than cold start performance.
 
 ## Quick Start
 
@@ -11,34 +36,58 @@ uv sync
 # 2. Authenticate with Modal (first time only - opens browser)
 uv run modal token new
 
-# 3. Configure Modal secrets (dev and prod)
-modal secret create dev \
-  ENVIRONMENT=dev \
-  PINECONE_API_KEY=your_pinecone_api_key \
-  R2_ACCOUNT_ID=your_r2_account_id \
-  R2_ACCESS_KEY_ID=your_r2_access_key_id \
-  R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
-
-modal secret create prod \
-  ENVIRONMENT=prod \
-  PINECONE_API_KEY=your_pinecone_api_key \
-  R2_ACCOUNT_ID=your_r2_account_id \
-  R2_ACCESS_KEY_ID=your_r2_access_key_id \
-  R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
-
-# 4. Start dev server (hot-reloads on file changes, uses "dev" secret)
+# 3. Start dev server
 uv run dev
 ```
 
 Note: `uv run` automatically uses the virtual environment - no need to activate it manually.
 
+## Development CLI
+
+### Local Development (Combined App)
+
+For local development, use the combined app that includes all services in one:
+
+| Command | Description |
+|---------|-------------|
+| `uv run dev` | Run combined dev app (server + search + processing in one) |
+
+This uses `apps/dev_combined.py` which combines all three services into a single Modal app. Benefits:
+- Hot-reload works on all services (server, search, processing)
+- No cross-app lookup issues
+- Easy to iterate on any part of the system
+
+**Note:** Cold starts will be slower since all dependencies load together, but this is acceptable for local development where iteration speed matters more than cold start performance.
+
+### Individual Apps (For Testing/Debugging)
+
+You can also run individual apps if needed:
+
+| Command | Description |
+|---------|-------------|
+| `uv run server` | Run just the API server |
+| `uv run search` | Run just the search app |
+| `uv run processing` | Run just the processing app |
+
+
+**Note:** Cross-app communication only works between deployed apps, not ephemeral serve apps. For full system testing, use `uv run dev` (combined app) or deploy the apps.
+
 ## How It Works
 
-- `main.py` defines a Modal App with a `Server` class
-- `/upload` endpoint accepts video files and spawns background processing jobs
+### Production Architecture (staging/prod)
+
+- `apps/server.py` - API gateway, delegates heavy work to other apps via `modal.Cls.from_name()`
+- `apps/search_app.py` - Handles semantic search queries with CLIP text encoder
+- `apps/processing_app.py` - Processes video uploads (chunking, embedding, storage)
+- Cross-app communication uses Modal's `Cls.from_name()` for lookups and `spawn()`/`remote()` for calls
 - Environment variables stored in Modal secrets (no .env files needed)
-- `uv run dev` automatically uses "dev" secret for development
-- Production deployment handled via CI/CD or direct Modal CLI
+
+### Local Development Architecture (dev)
+
+- `apps/dev_combined.py` - All three services in one app for easy iteration
+- Uses `api/fastapi_router.py` (configured for dev combined mode) which accepts worker class references instead of doing lookups
+- No cross-app lookups needed - services call each other directly within the same app
+- Hot-reload works on all services simultaneously
 
 ## Managing Dependencies
 
@@ -56,3 +105,13 @@ uv run pytest                    # Run all tests
 uv run pytest -v                 # Verbose output
 uv run pytest --cov              # With coverage
 ```
+
+Note: Some integration tests require `ffmpeg` to be installed locally.
+
+## Deployment
+
+Deployment is handled via GitHub Actions CI/CD. **Only the individual apps are deployed** (not dev_combined.py):
+
+1. `processing_app.py` (heavy dependencies)
+2. `search_app.py` (medium dependencies)
+3. `server.py` (API gateway - depends on the other two)

backend/api/fastapi_router.py

@@ -3,21 +3,83 @@
 import logging
 import time
 import uuid
-from fastapi import APIRouter, Form, HTTPException, UploadFile
+
+import modal
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
 
 logger = logging.getLogger(__name__)
 
+
 class FastAPIRouter:
-    def __init__(self, server_instance, is_internal_env):
+    def __init__(
+        self,
+        server_instance,
+        is_internal_env: bool,
+        environment: str = "dev",
+        search_service_cls=None,
+        processing_service_cls=None
+    ):
         """
         Initializes the API routes, giving them access to the server instance
         for calling background tasks and accessing shared state.
+
+        Args:
+            server_instance: The Modal server instance for accessing connectors and spawning local methods
+            is_internal_env: Whether this is an internal (dev/staging) environment
+            environment: Environment name (dev, staging, prod) for cross-app lookups
+            search_service_cls: Optional SearchService class for dev combined mode (direct access)
+            processing_service_cls: Optional ProcessingService class for dev combined mode (direct access)
         """
         self.server_instance = server_instance
         self.is_internal_env = is_internal_env
+        self.environment = environment
+        self.search_service_cls = search_service_cls
+        self.processing_service_cls = processing_service_cls
         self.router = APIRouter()
+
+        # Initialize UploadHandler with process_video spawn function
+        from services.upload import UploadHandler
+        self.upload_handler = UploadHandler(
+            job_store=server_instance.job_store,
+            process_video_spawn_fn=self._get_process_video_spawn_fn()
+        )
+
         self._register_routes()
 
+    def _get_process_video_spawn_fn(self):
+        """
+        Create a spawn function that works in both dev combined and production modes.
+
+        Returns:
+            Callable that spawns process_video_background
+        """
+        def spawn_process_video(video_bytes: bytes, filename: str, job_id: str, namespace: str, parent_batch_id: str):
+            try:
+                if self.processing_service_cls:
+                    # Dev combined mode - direct access
+                    self.processing_service_cls().process_video_background.spawn(
+                        video_bytes, filename, job_id, namespace, parent_batch_id
+                    )
+                    logger.info(f"[Upload] Spawned processing job {job_id} (dev combined mode)")
+                else:
+                    # Production mode - cross-app call
+                    from shared.config import get_modal_environment
+                    processing_app_name = f"{self.environment} processing"
+                    ProcessingService = modal.Cls.from_name(
+                        processing_app_name,
+                        "ProcessingService",
+                        environment_name=get_modal_environment()
+                    )
+                    ProcessingService().process_video_background.spawn(
+                        video_bytes, filename, job_id, namespace, parent_batch_id
+                    )
+                    logger.info(f"[Upload] Spawned processing job {job_id} to {processing_app_name}")
+            except Exception as e:
+                logger.error(f"[Upload] Failed to spawn processing job {job_id}: {e}")
+                raise
+
+        return spawn_process_video
+
     def _register_routes(self):
         """Registers all the FastAPI routes."""
         self.router.add_api_route("/health", self.health, methods=["GET"])
@@ -59,40 +121,23 @@ async def status(self, job_id: str):
             }
         return job_data
 
-    async def upload(self, file: UploadFile, namespace: str = Form("")):
+    async def upload(self, files: list[UploadFile] = File(default=[]), namespace: str = Form("")):
         """
         Handle video file upload and start background processing.
+        Supports both single and batch uploads.
 
         Args:
-            file (UploadFile): The uploaded video file.
+            files (list[UploadFile]): List of uploaded video file(s). Client sends files with repeated 'files' field names, which FastAPI collects into a list.
             namespace (str, optional): Namespace for Pinecone and R2 storage (default: "")
 
         Returns:
-            dict: Contains job_id, filename, content_type, size_bytes, status, and message.
-        """
-        contents = await file.read()
-        file_size = len(contents)
-        job_id = str(uuid.uuid4())
-
-        self.server_instance.job_store.create_job(job_id, {
-            "job_id": job_id,
-            "filename": file.filename,
-            "status": "processing",
-            "size_bytes": file_size,
-            "content_type": file.content_type,
-            "namespace": namespace
-        })
+            dict: For single upload: job_id, filename, etc.
+                  For batch upload: batch_job_id, total_videos, child_jobs, etc.
 
-        self.server_instance.process_video_background.spawn(contents, file.filename, job_id, namespace)
-
-        return {
-            "job_id": job_id,
-            "filename": file.filename,
-            "content_type": file.content_type,
-            "size_bytes": file_size,
-            "status": "processing",
-            "message": "Video uploaded successfully, processing in background"
-        }
+        Raises:
+            HTTPException: 400 if validation fails, 500 if processing errors
+        """
+        return await self.upload_handler.handle_upload(files, namespace)
 
     async def search(self, query: str, namespace: str = "", top_k: int = 10):
         """
@@ -113,14 +158,23 @@ async def search(self, query: str, namespace: str = "", top_k: int = 10):
             t_start = time.perf_counter()
             logger.info(f"[Search] Query: '{query}' | namespace='{namespace}' | top_k={top_k}")
 
-            results = self.server_instance.searcher.search(
-                query=query,
-                top_k=top_k,
-                namespace=namespace
-            )
+            # Call search app
+            if self.search_service_cls:
+                # Dev combined mode - direct access to worker in same app
+                results = self.search_service_cls().search.remote(query, namespace, top_k)
+            else:
+                # Production mode - cross-app call via from_name
+                from shared.config import get_modal_environment
+                search_app_name = f"{self.environment} search"
+                SearchService = modal.Cls.from_name(
+                    search_app_name,
+                    "SearchService",
+                    environment_name=get_modal_environment()
+                )
+                results = SearchService().search.remote(query, namespace, top_k)
 
             t_done = time.perf_counter()
-            logger.info(f"[Search] Found {len(results)} chunk-level results in {t_done - t_start:.3f}s")
+            logger.info(f"[Search] Found {len(results)} results in {t_done - t_start:.3f}s")
 
             return {
                 "query": query,

backend/apps/__init__.py

@@ -0,0 +1,2 @@
+# Modal apps package
+# Contains separate Modal apps for Server, Search, and Processing