Staging -> main

.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/__init__.py

@@ -1,3 +1,4 @@
-from .fastapi_router import FastAPIRouter
+from .server_fastapi_router import ServerFastAPIRouter
+from .search_fastapi_router import SearchFastAPIRouter
 
-__all__ = ["FastAPIRouter"]
+__all__ = ["ServerFastAPIRouter", "SearchFastAPIRouter"]