ref

ARCHITECTURE_AUDIT_REPORT.md

@@ -1,331 +0,0 @@
-# Codebase Architecture Audit Report
-
-## Executive Summary
-
-Completed comprehensive audit of the codebase to identify services and patterns that could benefit from refactoring similar to the credit service middleware-centric approach.
-
-**Audit Date:** 2025-12-15  
-**Files Analyzed:** 50+ files across routers/, services/, core/  
-**Focus Areas:** Service architecture, transaction patterns, middleware opportunities
-
----
-
-## ✅ What's Already Good
-
-### 1. Clean Router Layer
-- ✅ **No direct database commits** in routers
-- ✅ All routers use `QueryService` for data access
-- ✅ Proper dependency injection pattern
-- ✅ Auth handled by middleware (not manual in each endpoint)
-
-### 2. Well-Structured Services
-- ✅ `CreditService` - Fully middleware-driven with transaction tracking
-- ✅ `AuthService` - Middleware-based authentication
-- ✅ `DBService` - QueryService pattern for data access
-- ✅ `BackupService` - Async background uploads
-- ✅ `DriveService` - Google Drive integration
-- ✅ `EncryptionService` - Crypto utilities
-- ✅ `RazorpayService` - Payment gateway integration
-- ✅ `EmailService` - Email sending
-- ✅ `GeminiService` - AI service integration
-
----
-
-## 🔍 Issues Found
-
-### CRITICAL: Audit Logging Inconsistency
-
-**Location:** `routers/blink.py` (Lines 547, 563)
-
-**Problem:**
-```python
-# Direct AuditLog creation in router
-audit_log = AuditLog(
-    log_type="client",
-    user_id=server_user_id,
-    ...
-)
-db.add(audit_log)
-```
-
-**Why It's Bad:**
-- Bypasses `AuditService.log_event()` 
-- Inconsistent with other audit logging
-- No centralized audit logic
-- Manual field population (error-prone)
-
-**Recommendation:** Refactor to use `AuditService`
-
----
-
-## 📋 Refactoring Opportunities
-
-### 1. **Audit Service → Audit Middleware** (RECOMMENDED)
-
-**Current State:**
-- `AuditService.log_event()` called manually in endpoints
-- Some endpoints create `AuditLog` directly (`blink.py`)
-- Inconsistent usage across codebase
-
-**Proposed Refactoring:**
-Create `AuditMiddleware` similar to `CreditMiddleware`:
-
-```python
-class AuditMiddleware:
-    """Automatically log all requests/responses."""
-    
-    async def dispatch(self, request, call_next):
-        # Capture request details
-        start_time = time.time()
-        
-        # Process request
-        response = await call_next(request)
-        
-        # Automatically log based on response
-        duration = time.time() - start_time
-        await self.log_request(request, response, duration)
-        
-        return response
-```
-
-**Benefits:**
-- ✅ Every request automatically logged
-- ✅ Consistent audit trail
-- ✅ Routers unaware of audit logging
-- ✅ Centralized logging logic
-- ✅ No manual logging calls needed
-
-**Effort:** Medium (2-3 days)
-
----
-
-### 2. **Email Service → Email Queue** (OPTIONAL)
-
-**Current State:**
-- `EmailService` sends emails synchronously
-- Endpoint waits for email to send
-- No retry mechanism
-- No email queue
-
-**Proposed Refactoring:**
-Add background email queue:
-
-```python
-# Instead of:
-await EmailService.send_email(...)
-
-# Use:
-await EmailQueue.enqueue(
-    to="user@example.com",
-    subject="...",
-    body="..."
-)
-# Returns immediately, email sent in background
-```
-
-**Benefits:**
-- ✅ Faster API responses
-- ✅ Automatic retries on failure
-- ✅ Email history/tracking
-- ✅ Rate limiting built-in
-
-**Effort:** High (4-5 days)
-
----
-
-### 3. **API Key Manager → API Key Middleware** (OPTIONAL)
-
-**Current State:**
-- `api_key_manager.py` manages Gemini API keys
-- Manual rotation logic
-- No automatic rate limiting per key
-
-**Proposed Refactoring:**
-Add middleware for automatic key rotation and rate limiting:
-
-```python
-class APIKeyMiddleware:
-    """Automatically select and rotate API keys."""
-    
-    async def dispatch(self, request, call_next):
-        if self.is_gemini_request(request):
-            api_key = await self.get_available_key()
-            request.state.gemini_api_key = api_key
-        
-        response = await call_next(request)
-        
-        # Track usage
-        await self.track_key_usage(api_key, response)
-        
-        return response
-```
-
-**Benefits:**
-- ✅ Automatic key selection
-- ✅ Per-key rate limiting
-- ✅ Automatic rotation on errors
-- ✅ Usage analytics
-
-**Effort:** Medium (3-4 days)
-
----
-
-### 4. **Payment Transaction Tracking** (NICE TO HAVE)
-
-**Current State:**
-- `PaymentTransaction` model exists
-- Records created in `routers/payments.py`
-- No transaction history endpoint
-- No failed payment tracking
-
-**Proposed Enhancement:**
-Add `PaymentTransactionManager` similar to `CreditTransactionManager`:
-
-```python
-class PaymentTransactionManager:
-    """Centralized payment transaction management."""
-    
-    @staticmethod
-    async def create_order(...):
-        # Create payment transaction
-        # Record attempt
-        # Return order details
-    
-    @staticmethod
-    async def verify_payment(...):
-        # Verify signature
-        # Update transaction
-        # Trigger credit addition
-```
-
-**Benefits:**
-- ✅ Centralized payment logic
-- ✅ Better error tracking
-- ✅ Payment analytics
-- ✅ Audit trail
-
-**Effort:** Low (1-2 days)
-
----
-
-## 🎯 Recommended Action Plan
-
-### Phase 1: Critical Fixes (Do Now)
-1. **Fix `blink.py` audit logging** - Use `AuditService` instead of direct `AuditLog` creation
-   - **Effort:** 1 hour
-   - **Priority:** HIGH
-   - **Impact:** Consistency, maintainability
-
-### Phase 2: High-Value Refactorings (Do Soon)
-2. **Implement Audit Middleware**
-   - **Effort:** 2-3 days
-   - **Priority:** MEDIUM-HIGH
-   - **Impact:** Automatic request logging, better audit trail
-
-3. **Implement Job Deletion Credit Refunds**
-   - **Effort:** 4 hours (already has TODO)
-   - **Priority:** MEDIUM
-   - **Impact:** Complete credit service feature set
-
-### Phase 3: Optional Enhancements (Do Later)
-4. **Email Queue System**
-   - **Effort:** 4-5 days
-   - **Priority:** LOW-MEDIUM
-   - **Impact:** Better UX, reliability
-
-5. **Payment Transaction Manager**
-   - **Effort:** 1-2 days
-   - **Priority:** LOW
-   - **Impact:** Better analytics, tracking
-
-6. **API Key Middleware**
-   - **Effort:** 3-4 days
-   - **Priority:** LOW
-   - **Impact:** Better key management
-
----
-
-## 📊 Service Health Summary
-
-| Service | Status | Architecture | Notes |
-|---------|--------|--------------|-------|
-| CreditService | ✅ Excellent | Middleware-driven | Recently refactored, production-ready |
-| AuthService | ✅ Good | Middleware-based | Clean, well-tested |
-| DBService | ✅ Good | QueryService pattern | Consistent usage |
-| AuditService | ⚠️ Needs Work | Mixed (service + direct) | Inconsistent usage in blink.py |
-| BackupService | ✅ Good | Background async | Works well |
-| DriveService | ✅ Good | Utility service | Simple, effective |
-| EmailService | ⚠️ Could Improve | Synchronous | No queue, no retries |
-| RazorpayService | ✅ Good | Integration wrapper | Clean interface |
-| GeminiService | ✅ Good | Job queue pattern | Well-structured |
-| APIKeyManager | ⚠️ Could Improve | Manual management | No middleware integration |
-
----
-
-## 🔧 Technical Debt Items
-
-### Found During Audit
-
-1. **`blink.py` audit logging** - Direct `AuditLog` creation
-2. **Job deletion refunds** - TODO comment in `gemini.py:564`
-3. **Email sending** - No queue or async processing
-4. **API key rotation** - Manual, not middleware-driven
-5. **Payment analytics** - No aggregated stats endpoints
-
----
-
-## 💡 Key Learnings from Credit Service Refactoring
-
-**What Worked Well:**
-1. ✅ Middleware pattern for cross-cutting concerns
-2. ✅ Transaction manager for centralized logic
-3. ✅ Response inspection for automatic actions
-4. ✅ Complete audit trail via transaction table
-5. ✅ Zero application awareness
-
-**Apply These Patterns To:**
-- Audit logging (middleware)
-- Email sending (queue + manager)
-- API key management (middleware)
-- Payment tracking (transaction manager)
-
----
-
-## 🚀 Next Steps
-
-### Immediate (This Week)
-1. Fix `blink.py` to use `AuditService`
-2. Implement job deletion credit refunds (TODO)
-3. Add tests for audit service
-
-### Short-Term (This Month)
-4. Design and implement `AuditMiddleware`
-5. Add payment transaction history endpoint
-6. Improve error handling across services
-
-### Long-Term (Next Quarter)
-7. Implement email queue system
-8. Add API key middleware
-9. Build service health monitoring dashboard
-
----
-
-## 📈 Conclusion
-
-**Overall Codebase Health: 8.5/10**
-
-The codebase is generally well-structured with good separation of concerns. The recent credit service refactoring demonstrates a strong pattern that can be applied to other services.
-
-**Main Strengths:**
-- Clean router layer
-- Middleware-centric architecture
-- Good service patterns
-- Comprehensive testing
-
-**Areas for Improvement:**
-- Audit logging consistency
-- Async processing (emails)
-- Service middleware adoption
-
-**Recommended Focus:**
-Start with Phase 1 critical fixes, then evaluate Phase 2 based on business priorities.

CREDIT_AUDIT_REPORT.md

@@ -1,169 +0,0 @@
-# Credit Code Audit Report
-
-## Executive Summary
-
-Completed full codebase audit for credit operations. **All legacy credit code has been removed or deprecated.**
-
-All credit operations now flow through one of two paths:
-1. **Middleware** → `CreditTransactionManager` (for API endpoints)
-2. **Payment Router** → `CreditTransactionManager` (for purchases)
-
----
-
-## Changes Made
-
-### ✅ 1. Deprecated Legacy Credit Dependencies (`dependencies.py`)
-
-**REMOVED:**
-- `verify_credits()` - Manually deducted 1 credit
-- `verify_video_credits()` - Manually deducted 10 credits
-
-**STATUS:** Commented out with deprecation notice
-
-These functions directly manipulated `user.credits` without creating transaction records, bypassing the audit trail.
-
----
-
-### ✅ 2. Removed Manual Refunds (`routers/gemini.py`)
-
-**REMOVED:**
-- Lines 572, 583: Manual `user.credits +=` in `delete_job` endpoint
-- Complex refund logic based on job status
-
-**REASON:** 
-- Job deletion refunds should be handled by `CreditTransactionManager.refund_credits()` for proper tracking
-- Added TODO comment for future implementation
-
-**IMPACT:** 
-- `DELETE /gemini/job/{job_id}` now returns `refund_amount: 0`
-- Soft deletion still works, just no automatic refunds yet
-- Can be re-implemented properly using transaction manager later
-
----
-
-### ✅ 3. Updated Comments (`routers/gemini.py`)
-
-**CHANGED:**
-```python
-# Old comment
-# Authentication is handled by dependencies.verify_credits
-
-# New comment  
-# Authentication and credit handling is managed automatically by middleware.
-```
-
----
-
-## Credit Operations Inventory
-
-### ✅ GOOD: Using CreditTransactionManager
-
-1. **Middleware** (`services/credit_service/middleware.py`)
-   - `CreditTransactionManager.reserve_credits()`
-   - `CreditTransactionManager.confirm_credits()`
-   - `CreditTransactionManager.refund_credits()`
-
-2. **Payment Router** (`routers/payments.py`)
-   - `CreditTransactionManager.add_credits()`
-
-3. **Transaction Manager** (`services/credit_service/transaction_manager.py`)
-   - `user.credits +=` (Line 272, 329) - ✅ OK (within transaction manager)
-   - `user.credits -=` (Line 129) - ✅ OK (within transaction manager)
-
-### ✅ LEGACY BUT ACCEPTABLE: Job Lifecycle Management
-
-4. **Credit Manager** (`services/credit_service/credit_manager.py`)
-   - `user.credits -=` (Line 113) - ✅ OK (`reserve_credit` for job workers)
-   - `user.credits +=` (Line 175) - ✅ OK (`refund_credit` for job workers)
-   
-**WHY ACCEPTABLE:** 
-- These are called by background workers, not API endpoints
-- Used for job lifecycle management (queued → processing → completed/failed)
-- Part of the existing system that works alongside middleware
-- Middleware handles initial reservation, credit_manager handles job completion refunds
-
-### ❌ REMOVED: Direct API Endpoint Manipulation
-
-5. **Dependencies** (`dependencies.py`) - DEPRECATED ✅
-6. **Gemini Router** (`routers/gemini.py`) - REMOVED ✅
-
----
-
-## Test Files
-
-The following files have direct credit manipulation for TESTING purposes only:
-- `tests/test_job_lifecycle.py`
-- `tests/test_worker_pool.py`
-
-**ACTION:** None needed - test files can manipulate credits directly for test scenarios
-
----
-
-## Final Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                     USER REQUEST                         │
-└──────────────────────┬──────────────────────────────────┘
-                       │
-          ┌────────────┴────────────┐
-          │                         │
-    API Endpoints              Payment Endpoints
-          │                         │
-          ▼                         ▼
-   ┌─────────────┐          ┌─────────────┐
-   │ Middleware  │          │   Payment   │
-   │   Handles   │          │   Router    │
-   │   Credits   │          │             │
-   └──────┬──────┘          └──────┬──────┘
-          │                        │
-          │    ┌──────────────────┐│
-          └────►CreditTransaction◄┘
-               │   Manager        │
-               │(Single Source of │
-               │     Truth)       │
-               └────────┬─────────┘
-                        │
-                        ▼
-               ┌────────────────┐
-               │  credit_       │
-               │  transactions  │
-               │  table         │
-               └────────────────┘
-```
-
-All credit database operations go through `CreditTransactionManager` ✅
-
----
-
-## Verification Checklist
-
-- [x] No `Depends(verify_credits)` in any router
-- [x] No `Depends(verify_video_credits)` in any router  
-- [x] No direct `user.credits +=` in routers (except legacy code commented)
-- [x] No direct `user.credits -=` in routers (except legacy code commented)
-- [x] Middleware uses `CreditTransactionManager`
-- [x] Payment router uses `CreditTransactionManager`
-- [x] All credit changes create transaction records
-- [x] Complete audit trail available
-
----
-
-## Remaining Work (Optional)
-
-1. **Job Deletion Refunds** - Re-implement using `CreditTransactionManager`
-2. **Delete Legacy Code** - After confirming migration works, delete commented functions
-3. **Async Job Credit Handling** - Ensure middleware properly handles job status checks
-4. **Test Suite** - Add tests for new transaction-based credit system
-
----
-
-## Conclusion
-
-✅ **All legacy credit misuse has been eliminated.**  
-✅ **Single source of truth: `CreditTransactionManager`**  
-✅ **Complete audit trail for all operations**  
-✅ **Middleware handles API credits automatically**  
-✅ **Payment router properly tracks purchases**  
-
-The codebase is now clean and follows the centralized credit management architecture.

FINAL_ARCHITECTURE_AUDIT.md

@@ -1,294 +0,0 @@
-# Final Codebase Architecture Audit Report
-
-## 🎯 Executive Summary
-
-**Status:** ✅ **EXCELLENT** - Codebase is in great shape!
-
-After comprehensive analysis, the architecture is **production-ready** with no critical issues remaining.
-
----
-
-## ✅ What's Perfect
-
-### 1. **Routers Are Completely Clean**
-- ❌ No `db.commit()` calls in routers
-- ❌ No `session.add()` calls in routers  
-- ❌ No `AuditLog()` direct creation
-- ❌ No `user.credits +=` manual operations
-- ✅ All routers use services/managers properly
-
-### 2. **Middleware Stack is Complete**
-```
-Auth → Audit → API Key → Credit → Application
-```
-All cross-cutting concerns handled automatically!
-
-### 3. **Service Architecture is Consistent**
-
-| Service | Type | Status |
-|---------|------|--------|
-| **Auth Service** | Middleware | ✅ Perfect |
-| **Audit Service** | Middleware | ✅ Perfect |
-| **API Key Service** | Middleware | ✅ Perfect |
-| **Credit Service** | Middleware + Manager | ✅ Perfect |
-| **Payment Service** | Transaction Manager | ✅ Perfect |
-| **DB Service** | QueryService Pattern | ✅ Perfect |
-| **Backup Service** | Async Service | ✅ Perfect |
-| **Drive Service** | Utility Service | ✅ Good |
-| **Email Service** | Utility Service | ✅ Good |
-| **Encryption Service** | Utility Service | ✅ Good |
-| **Razorpay Service** | Integration Service | ✅ Good |
-
----
-
-## 💡 Optional Minor Enhancements
-
-These are **NOT required** but could add value in the future:
-
-### 1. Email Queue System (Low Priority)
-
-**Current State:**
-```python
-# Email is sent synchronously
-await send_email(to_email, subject, body)
-# Endpoint waits for email to send
-```
-
-**Enhancement:**
-```python
-# Email queue for async processing
-await EmailQueue.enqueue(to_email, subject, body)
-# Returns immediately, email sent in background
-```
-
-**Benefits:**
-- Faster API responses
-- Automatic retries on failure
-- Email history tracking
-- Rate limiting
-
-**Effort:** 1-2 days  
-**Priority:** LOW (only if sending many emails)
-
----
-
-### 2. Job Deletion Credit Refunds (Medium Priority)
-
-**Current State:**
-```python
-# DELETE /gemini/job/{job_id}
-# TODO: Implement credit refund via CreditTransactionManager
-```
-
-**Enhancement:**
-Implement proper refund logic using `CreditTransactionManager.refund_credits()`
-
-**Benefits:**
-- Fair refunds for cancelled jobs
-- Uses existing transaction manager
-- Complete audit trail
-
-**Effort:** 2-3 hours  
-**Priority:** MEDIUM (if users delete jobs frequently)
-
----
-
-### 3. API Key Health Dashboard (Nice to Have)
-
-**Enhancement:**
-```
-GET /admin/api-keys/health
-{
-    "total_keys": 3,
-    "healthy_keys": 2,
-    "keys_in_cooldown": 1,
-    "quota_remaining": "55%"
-}
-```
-
-**Benefits:**
-- Monitor key health
-- Proactive quota management
-- Better debugging
-
-**Effort:** 3-4 hours  
-**Priority:** LOW (nice-to-have for monitoring)
-
----
-
-## 🔍 Detailed Audit Findings
-
-### Services Analyzed
-
-**1. Email Service** (`services/email_service.py`)
-- ✅ Clean implementation
-- ✅ Gmail API + SMTP fallback
-- ℹ️ Synchronous (acceptable for current use)
-- 💡 Could add email queue (optional)
-
-**2. Backup Service** (`services/backup_service/`)
-- ✅ Async implementation
-- ✅ Debouncing to prevent excessive uploads
-- ✅ Lock mechanism to prevent concurrent uploads
-- ✅ Force option for critical backups
-- ✅ **Perfect!**
-
-**3. Drive Service** (`services/drive_service.py`)
-- ✅ Google Drive integration
-- ✅ Upload/download functionality
-- ✅ Clean implementation
-- ✅ **No changes needed**
-
-**4. Encryption Service** (`services/encryption_service.py`)
-- ✅ Crypto utilities
-- ✅ Clean implementation
-- ✅ **No changes needed**
-
-**5. Razorpay Service** (`services/razorpay_service.py`)
-- ✅ Payment gateway integration
-- ✅ Signature verification
-- ✅ Works with PaymentTransactionManager
-- ✅ **No changes needed**
-
-**6. API Key Manager** (`services/api_key_manager.py`)
-- ✅ Usage tracking
-- ✅ Least-used selection
-- ✅ Works with APIKeyMiddleware
-- ✅ **No changes needed**
-
----
-
-## 📊 Code Quality Metrics
-
-### Architecture Patterns
-
-| Pattern | Count | Status |
-|---------|-------|--------|
-| **Middleware** | 4 | ✅ Excellent |
-| **Transaction Managers** | 2 | ✅ Excellent |
-| **Service Classes** | 10+ | ✅ Good |
-| **Direct DB Operations in Routers** | 0 | ✅ Perfect |
-| **Manual Credit Operations** | 0 | ✅ Perfect |
-| **Direct Audit Log Creation** | 0 | ✅ Perfect |
-
-### Test Coverage
-
-| Component | Tests | Coverage |
-|-----------|-------|----------|
-| Credit Service | ✅ 55+ tests | 90%+ |
-| Other Services | ⚠️ Minimal | TBD |
-
-**Recommendation:** Add tests for audit, API key, and payment services (future work)
-
----
-
-## 🎯 Current Architecture Diagram
-
-```
-┌─────────────────────────────────────────────┐
-│              USER REQUEST                    │
-└───────────────┬─────────────────────────────┘
-                │
-        ┌───────▼────────┐
-        │  CORS Middleware│
-        └───────┬────────┘
-                │
-        ┌───────▼────────┐
-        │ Auth Middleware │  ← Authenticate user
-        └───────┬────────┘
-                │
-      ┌─────────▼──────────┐
-      │ Audit Middleware    │  ← Log request/response
-      └─────────┬──────────┘
-                │
-    ┌───────────▼────────────┐
-    │ API Key Middleware      │  ← Select Gemini key
-    └───────────┬────────────┘
-                │
-      ┌─────────▼──────────┐
-      │ Credit Middleware   │  ← Reserve/confirm credits
-      └─────────┬──────────┘
-                │
-        ┌───────▼────────┐
-        │   Application   │  ← Business logic
-        │    Endpoints    │
-        └───────┬────────┘
-                │
-    ┌───────────▼────────────┐
-    │  Service Layer          │
-    │  - CreditTransactionMgr │
-    │  - PaymentTransactionMgr│
-    │  - QueryService         │
-    │  - BackupService        │
-    │  - EmailService         │
-    └───────────┬────────────┘
-                │
-        ┌───────▼────────┐
-        │    Database     │
-        └─────────────────┘
-```
-
----
-
-## ✅ Final Recommendations
-
-### Do Now (Critical): **NONE!** 🎉
-Everything critical is complete and working!
-
-### Do Soon (High Value):
-1. **Job Deletion Refunds** (2-3 hours)
-   - Implement using `CreditTransactionManager.refund_credits()`
-   - Complete the TODO in `gemini.py:564`
-
-### Do Later (Nice to Have):
-2. **Email Queue** (1-2 days)
-   - Only if sending many emails
-   - Current sync approach works fine for low volume
-
-3. **API Key Health Endpoint** (3-4 hours)
-   - Monitoring dashboard
-   - Not essential but nice for ops
-
-4. **Test Suite Expansion** (3-5 days)
-   - Add tests for audit middleware
-   - Add tests for API key middleware
-   - Add tests for payment manager
-
----
-
-## 🏆 Achievement Summary
-
-**What We Accomplished:**
-
-1. ✅ **Credit System** - Fully middleware-driven with complete audit trail
-2. ✅ **Audit Logging** - Automatic request/response logging
-3. ✅ **API Key Management** - Smart rotation with quota recovery
-4. ✅ **Payment System** - Centralized transaction management + analytics
-5. ✅ **Clean Architecture** - Zero direct DB operations in routers
-6. ✅ **Consistent Patterns** - Middleware + transaction managers
-
-**Code Quality:**
-- **Clean Routers** - 100% service-driven
-- **Middleware Stack** - 4 layers of automatic processing
-- **Transaction Managers** - 2 centralized managers
-- **Test Coverage** - 90%+ for credit service
-- **Zero Tech Debt** - No critical issues remaining
-
----
-
-## 🎉 Conclusion
-
-**The codebase is production-ready!**
-
-**Architecture Grade: A+**
-
-All critical refactoring complete. The optional enhancements are truly optional - the system works great as-is.
-
-**Next Steps:**
-1. ✅ Code is deployed (main branch)
-2. ✅ All 4 phases complete
-3. ⏳ **Test in production**
-4. ⏳ **Monitor performance**
-5. ⏳ **Consider optional enhancements based on usage**
-
-**Congratulations! 🎊**

app.py

@@ -1,8 +1,5 @@
 """
-FastAPI URL Blink Application
-
-Production-grade API for receiving encrypted user data,
-decrypting it, and storing in SQLite database.
+FastAPI Application - API Gateway with credit management and AI services.
 """
 import os
 import logging
@@ -29,10 +26,7 @@ drive_service = DriveService()
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    """
-    Application lifespan manager.
-    Initializes database on startup.
-    """
+    """Application lifespan manager."""
     logger.info("Starting up - initializing database...")
     
     # Register DB Service configuration
@@ -41,8 +35,6 @@ async def lifespan(app: FastAPI):
     
     # Initialize Backup Service
     from services.backup_service import initialize_backup_service
-    # Note: drive_service is already initialized globally, but re-initialized here as per instruction.
-    # The global drive_service is used later for download/upload.
     local_drive_service = DriveService() 
     backup_service = initialize_backup_service(
         local_drive_service,
@@ -109,7 +101,7 @@ async def lifespan(app: FastAPI):
                 "cost": 10,
                 "type": "async"
             },
-            #  Status check endpoints - inspect response for job completion
+
             "/gemini/job/{job_id}": {
                 "cost": 0,  # No additional cost for status checks
                 "type": "async"
@@ -191,36 +183,35 @@ app = FastAPI(
     lifespan=lifespan
 )
 
-# Configure CORS
-# For cookies to work with credentials, we need specific origins (not "*")
+
 allowed_origins = os.getenv("CORS_ORIGINS", "http://localhost:3000,http://localhost:5173").split(",")
 logger.info(f"CORS allowed origins: {allowed_origins}")
 
 app.add_middleware(
     CORSMiddleware,
-    allow_origins=allowed_origins,  # Specific origins for production
+    allow_origins=allowed_origins,
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],
 )
 
-# Add Audit Middleware (executes second - after auth, before API key)
+
 from services.audit_service import AuditMiddleware
 app.add_middleware(AuditMiddleware)
 
-# Add API Key Middleware (executes third - for Gemini requests)
+
 from services.gemini_service import APIKeyMiddleware
 app.add_middleware(APIKeyMiddleware)
 
-# Add Credit Middleware (executes fourth - after auth, audit, and API key)
+
 from services.credit_service import CreditMiddleware
 app.add_middleware(CreditMiddleware)
 
-# Add Auth Middleware second (executes first - sets user)
+
 from services.auth_service import AuthMiddleware
 app.add_middleware(AuthMiddleware)
 
-# Include Routers
+
 app.include_router(general.router)
 app.include_router(auth.router)
 app.include_router(blink.router)
@@ -233,9 +224,7 @@ app.include_router(schema.router)
 
 @app.exception_handler(Exception)
 async def global_exception_handler(request: Request, exc: Exception):
-    """
-    Global exception handler for unhandled errors.
-    """
+    """Global exception handler."""
     logger.error(f"Unhandled exception: {exc}")
     return JSONResponse(
         status_code=500,

docs/CLIENT_INTEGRATION.md

@@ -1,287 +0,0 @@
-# Google Sign-In Client Integration Guide
-
-Quick guide for frontend developers to integrate Google Sign-In with the APIGateway.
-
-## Setup
-
-### 1. Get Your Google Client ID
-
-Use the same `GOOGLE_CLIENT_ID` that's configured on the backend.
-
-### 2. Add Google Identity Services Script
-
-```html
-<script src="https://accounts.google.com/gsi/client" async defer></script>
-```
-
----
-
-## Option A: One-Tap / Button Sign-In (Recommended)
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <script src="https://accounts.google.com/gsi/client" async defer></script>
-</head>
-<body>
-    <!-- Google One Tap prompt -->
-    <div id="g_id_onload"
-         data-client_id="YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com"
-         data-callback="handleGoogleSignIn"
-         data-auto_prompt="false">
-    </div>
-    
-    <!-- Sign In Button -->
-    <div class="g_id_signin"
-         data-type="standard"
-         data-size="large"
-         data-theme="outline"
-         data-text="sign_in_with"
-         data-shape="rectangular"
-         data-logo_alignment="left">
-    </div>
-
-    <script>
-    const API_BASE = 'https://your-api-gateway.com';  // Change this
-    
-    async function handleGoogleSignIn(response) {
-        try {
-            // Send Google token to your backend
-            const res = await fetch(`${API_BASE}/auth/google`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    id_token: response.credential,
-                    temp_user_id: localStorage.getItem('temp_user_id') // optional
-                })
-            });
-            
-            const data = await res.json();
-            
-            if (data.success) {
-                // Store the access token
-                localStorage.setItem('access_token', data.access_token);
-                localStorage.setItem('user', JSON.stringify({
-                    user_id: data.user_id,
-                    email: data.email,
-                    name: data.name,
-                    credits: data.credits
-                }));
-                
-                console.log('Signed in!', data.is_new_user ? 'New user' : 'Existing user');
-                // Redirect or update UI
-                window.location.reload();
-            } else {
-                alert('Sign in failed: ' + (data.detail || 'Unknown error'));
-            }
-        } catch (error) {
-            console.error('Sign in error:', error);
-            alert('Sign in failed. Please try again.');
-        }
-    }
-    </script>
-</body>
-</html>
-```
-
----
-
-## Option B: Programmatic Sign-In
-
-```javascript
-const API_BASE = 'https://your-api-gateway.com';
-
-// Initialize Google Sign-In
-function initGoogleSignIn(clientId) {
-    google.accounts.id.initialize({
-        client_id: clientId,
-        callback: handleGoogleSignIn
-    });
-    
-    // Render button in a container
-    google.accounts.id.renderButton(
-        document.getElementById('google-signin-btn'),
-        { theme: 'outline', size: 'large', text: 'signin_with' }
-    );
-}
-
-// Handle the response
-async function handleGoogleSignIn(response) {
-    const res = await fetch(`${API_BASE}/auth/google`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ id_token: response.credential })
-    });
-    
-    const data = await res.json();
-    if (data.success) {
-        localStorage.setItem('access_token', data.access_token);
-    }
-}
-
-// Call on page load
-window.onload = () => initGoogleSignIn('YOUR_CLIENT_ID.apps.googleusercontent.com');
-```
-
----
-
-## Making API Calls
-
-After sign-in, use the access token for all API calls:
-
-```javascript
-const API_BASE = 'https://your-api-gateway.com';
-
-async function apiCall(endpoint, options = {}) {
-    const token = localStorage.getItem('access_token');
-    
-    if (!token) {
-        throw new Error('Not signed in');
-    }
-    
-    const response = await fetch(`${API_BASE}${endpoint}`, {
-        ...options,
-        headers: {
-            'Authorization': `Bearer ${token}`,
-            'Content-Type': 'application/json',
-            ...options.headers
-        }
-    });
-    
-    if (response.status === 401) {
-        // Token expired - need to sign in again
-        localStorage.removeItem('access_token');
-        window.location.href = '/login';
-        return;
-    }
-    
-    return response.json();
-}
-
-// Examples
-async function getCurrentUser() {
-    return apiCall('/auth/me');
-}
-
-async function generateText(prompt) {
-    return apiCall('/gemini/generate-text', {
-        method: 'POST',
-        body: JSON.stringify({ prompt })
-    });
-}
-
-async function checkJobStatus(jobId) {
-    return apiCall(`/gemini/job/${jobId}`);
-}
-```
-
----
-
-## API Endpoints Reference
-
-| Endpoint | Method | Auth Required | Description |
-|----------|--------|---------------|-------------|
-| `/auth/google` | POST | ❌ | Sign in with Google token |
-| `/auth/me` | GET | ✅ | Get current user info |
-| `/auth/refresh` | POST | ❌ | Refresh access token |
-| `/gemini/generate-text` | POST | ✅ | Generate text (costs 1 credit) |
-| `/gemini/generate-video` | POST | ✅ | Generate video (costs 1 credit) |
-| `/gemini/job/{job_id}` | GET | ✅ | Check job status |
-
----
-
-## Sign Out
-
-```javascript
-function signOut() {
-    localStorage.removeItem('access_token');
-    localStorage.removeItem('user');
-    
-    // Optionally call logout endpoint for audit
-    fetch(`${API_BASE}/auth/logout`, {
-        method: 'POST',
-        headers: { 'Authorization': `Bearer ${token}` }
-    });
-    
-    // Revoke Google session
-    google.accounts.id.disableAutoSelect();
-    
-    window.location.href = '/';
-}
-```
-
----
-
-## Error Handling
-
-| Status | Meaning | Action |
-|--------|---------|--------|
-| 401 | Token expired/invalid | Redirect to sign-in |
-| 402 | Insufficient credits | Show "buy credits" prompt |
-| 429 | Rate limited | Wait and retry |
-
-```javascript
-async function apiCallWithErrorHandling(endpoint, options) {
-    const response = await apiCall(endpoint, options);
-    
-    if (response.status === 402) {
-        alert('You have run out of credits!');
-        return null;
-    }
-    
-    return response;
-}
-```
-
----
-
-## React Example
-
-```jsx
-import { useEffect, useState } from 'react';
-
-function App() {
-    const [user, setUser] = useState(null);
-    
-    useEffect(() => {
-        // Check if already signed in
-        const token = localStorage.getItem('access_token');
-        if (token) {
-            fetch('/auth/me', {
-                headers: { 'Authorization': `Bearer ${token}` }
-            })
-            .then(r => r.json())
-            .then(setUser)
-            .catch(() => localStorage.removeItem('access_token'));
-        }
-        
-        // Initialize Google Sign-In
-        window.handleGoogleSignIn = async (response) => {
-            const res = await fetch('/auth/google', {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ id_token: response.credential })
-            });
-            const data = await res.json();
-            if (data.success) {
-                localStorage.setItem('access_token', data.access_token);
-                setUser(data);
-            }
-        };
-    }, []);
-    
-    if (!user) {
-        return (
-            <div>
-                <div id="g_id_onload"
-                     data-client_id="YOUR_CLIENT_ID"
-                     data-callback="handleGoogleSignIn" />
-                <div className="g_id_signin" data-type="standard" />
-            </div>
-        );
-    }
-    
-    return <div>Welcome, {user.name}! Credits: {user.credits}</div>;
-}
-```

docs/GEMINI_API.md

@@ -1,230 +0,0 @@
-# Gemini API - Client Integration Guide
-
-## Authentication
-
-All endpoints require JWT authentication via Google Sign-In.
-
-```
-Authorization: Bearer <your_jwt_token>
-```
-
----
-
-## Endpoints
-
-### 1. Generate Text
-**POST** `/gemini/generate-text`
-
-```json
-{
-  "prompt": "Write a poem about the moon",
-  "model": "gemini-2.5-flash"  // optional
-}
-```
-
-**Response:**
-```json
-{
-  "success": true,
-  "job_id": "job_abc123",
-  "status": "queued",
-  "position": 1
-}
-```
-
----
-
-### 2. Analyze Image
-**POST** `/gemini/analyze-image`
-
-```json
-{
-  "base64_image": "<base64_encoded_image>",
-  "mime_type": "image/jpeg",
-  "prompt": "What's in this image?"
-}
-```
-
----
-
-### 3. Edit Image
-**POST** `/gemini/edit-image`
-
-```json
-{
-  "base64_image": "<base64_encoded_image>",
-  "mime_type": "image/jpeg",
-  "prompt": "Make the sky purple"
-}
-```
-
----
-
-### 4. Generate Video
-**POST** `/gemini/generate-video`
-
-```json
-{
-  "base64_image": "<base64_encoded_image>",
-  "mime_type": "image/jpeg",
-  "prompt": "Make this scene come alive with gentle motion",
-  "aspect_ratio": "16:9",    // or "9:16"
-  "resolution": "720p",       // or "1080p"
-  "number_of_videos": 1       // 1-4
-}
-```
-
----
-
-### 5. Generate Animation Prompt
-**POST** `/gemini/generate-animation-prompt`
-
-```json
-{
-  "base64_image": "<base64_encoded_image>",
-  "mime_type": "image/png",
-  "custom_prompt": null  // optional
-}
-```
-
----
-
-## Polling for Results
-
-All requests return a `job_id`. Poll for status:
-
-**GET** `/gemini/job/{job_id}`
-
-### Status Flow:
-```
-queued → processing → completed / failed
-```
-
-### Response Examples:
-
-**Queued:**
-```json
-{
-  "status": "queued",
-  "position": 3
-}
-```
-
-**Processing:**
-```json
-{
-  "status": "processing",
-  "started_at": "2024-12-12T13:00:00Z"
-}
-```
-
-**Completed (Text/Image/Analyze):**
-```json
-{
-  "status": "completed",
-  "output": {
-    "text": "Here is your poem..."
-  }
-}
-```
-
-**Completed (Video):**
-```json
-{
-  "status": "completed",
-  "output": {
-    "filename": "video_abc123.mp4"
-  },
-  "download_url": "/gemini/download/job_abc123"
-}
-```
-
-**Failed:**
-```json
-{
-  "status": "failed",
-  "error": "API rate limit exceeded"
-}
-```
-
----
-
-## Download Video
-
-**GET** `/gemini/download/{job_id}`
-
-Returns the video file directly.
-
----
-
-## Cancel Job
-
-**POST** `/gemini/job/{job_id}/cancel`
-
-Only works for `queued` jobs.
-
-```json
-{
-  "success": true,
-  "status": "cancelled"
-}
-```
-
----
-
-## Client Polling Example (JavaScript)
-
-```javascript
-async function generateText(prompt) {
-  // 1. Submit job
-  const response = await fetch('/gemini/generate-text', {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${token}`,
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify({ prompt })
-  });
-  const { job_id } = await response.json();
-
-  // 2. Poll until done
-  while (true) {
-    const status = await fetch(`/gemini/job/${job_id}`, {
-      headers: { 'Authorization': `Bearer ${token}` }
-    }).then(r => r.json());
-
-    if (status.status === 'completed') {
-      return status.output.text;
-    }
-    if (status.status === 'failed') {
-      throw new Error(status.error);
-    }
-    
-    // Wait before next poll
-    await new Promise(r => setTimeout(r, 2000));
-  }
-}
-```
-
----
-
-## Priority Tiers
-
-Jobs are processed with different priorities:
-
-| Job Type | Priority | Poll Interval |
-|----------|----------|---------------|
-| text, analyze, animation_prompt | Fast | ~5 sec |
-| image, edit_image | Medium | ~30 sec |
-| video | Slow | ~60 sec |
-
----
-
-## Error Codes
-
-| Code | Meaning |
-|------|---------|
-| 401 | Unauthorized - Invalid/expired token |
-| 402 | Insufficient credits |
-| 404 | Job not found |
-| 429 | Rate limit exceeded |

routers/gemini.py

@@ -1,7 +1,5 @@
 """
 Gemini Router - API endpoints for Gemini AI services.
-Uses job queue pattern for async processing.
-Authentication via JWT (Authorization: Bearer <token>).
 """
 import os
 import uuid
@@ -20,7 +18,7 @@ from datetime import datetime
 router = APIRouter(prefix="/gemini", tags=["gemini"])
 
 
-# Request/Response Models
+
 class GenerateAnimationPromptRequest(BaseModel):
     base64_image: str = Field(..., description="Base64 encoded image data")
     mime_type: str = Field(..., description="MIME type of the image (e.g., image/png)")
@@ -53,8 +51,7 @@ class AnalyzeImageRequest(BaseModel):
     prompt: str = Field(..., description="Analysis prompt")
 
 
-# Authentication and credit handling is managed automatically by middleware.
-# JWT tokens via Authorization: Bearer <token> header
+
 
 
 async def get_queue_position(db: AsyncSession, job_id: str) -> int:
@@ -74,7 +71,7 @@ async def create_job(
     input_data: dict,
     credits_reserved: int = 0
 ) -> GeminiJob:
-    """Create a new job in the queue with auto-assigned priority."""
+    """Create a new job in the queue."""
     from services.gemini_job_worker import get_priority_for_job_type, get_pool
     
     job_id = f"job_{uuid.uuid4().hex[:16]}"
@@ -82,18 +79,18 @@ async def create_job(
     
     job = GeminiJob(
         job_id=job_id,
-        user_id=user.id,  # Integer FK to users.id
+        user_id=user.id,
         job_type=job_type,
         status="queued",
         priority=priority,
         input_data=input_data,
-        credits_reserved=credits_reserved  # Track reserved credits for this job
+        credits_reserved=credits_reserved
     )
     db.add(job)
     await db.commit()
     await db.refresh(job)
     
-    # Notify workers immediately so they wake up and process this job
+
     get_pool().notify_new_job(priority)
     
     return job
@@ -105,10 +102,7 @@ async def generate_animation_prompt(
     request: GenerateAnimationPromptRequest,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Queue an animation prompt generation job.
-    Auth and credit validation handled by middleware.
-    """
+    """Queue an animation prompt generation job."""
     user = req.state.user
     credits_reserved = req.state.credits_reserved
     job = await create_job(
@@ -140,10 +134,7 @@ async def edit_image(
     request: EditImageRequest,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Queue an image edit job.
-    Auth and credit validation handled by middleware.
-    """
+    """Queue an image edit job."""
     user = req.state.user
     credits_reserved = req.state.credits_reserved
     job = await create_job(
@@ -175,10 +166,7 @@ async def generate_video(
     request: GenerateVideoRequest,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Queue a video generation job.
-    Auth and credit validation handled by middleware.
-    """
+    """Queue a video generation job."""
     user = req.state.user
     credits_reserved = req.state.credits_reserved
     job = await create_job(
@@ -193,7 +181,7 @@ async def generate_video(
             "resolution": request.resolution,
             "number_of_videos": request.number_of_videos
         },
-        credits_reserved=credits_reserved  # 10 credits for video
+        credits_reserved=credits_reserved
     )
     
     position = await get_queue_position(db, job.job_id)
@@ -213,10 +201,7 @@ async def generate_text(
     request: GenerateTextRequest,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Queue a text generation job.
-    Auth and credit validation handled by middleware.
-    """
+    """Queue a text generation job."""
     user = req.state.user
     credits_reserved = req.state.credits_reserved
     job = await create_job(
@@ -247,10 +232,7 @@ async def analyze_image(
     request: AnalyzeImageRequest,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Queue an image analysis job.
-    Auth and credit validation handled by middleware.
-    """
+    """Queue an image analysis job."""
     user = req.state.user
     credits_reserved = req.state.credits_reserved
     job = await create_job(
@@ -283,28 +265,23 @@ async def get_jobs(
     page: int = 1,
     limit: int = 20
 ):
-    """
-    Get all jobs created by the current user.
-    Returns a paginated list of jobs with status, type, and prompt (for video jobs).
-    Auth handled by AuthMiddleware - user in request.state.user
-    """
+    """Get all jobs for the current user."""
     user = req.state.user
     offset = (page - 1) * limit
     
-    # Query jobs for the current user
+
     query = select(GeminiJob).where(
-        GeminiJob.user_id == user.id  # Integer FK comparison
+        GeminiJob.user_id == user.id
     ).order_by(GeminiJob.created_at.desc()).offset(offset).limit(limit)
     
     result = await db.execute(query)
     jobs = result.scalars().all()
     
-    # Get total count
-    count_query = select(func.count()).where(GeminiJob.user_id == user.id)  # Integer FK comparison
+    count_query = select(func.count()).where(GeminiJob.user_id == user.id)
     count_result = await db.execute(count_query)
     total_count = count_result.scalar()
     
-    # Build job list
+
     job_list = []
     for job in jobs:
         job_item = {
@@ -313,18 +290,18 @@ async def get_jobs(
             "status": job.status,
             "created_at": job.created_at.isoformat() if job.created_at else None,
             "completed_at": job.completed_at.isoformat() if job.completed_at else None,
-            # "api_response": job.api_response,
+
         }
         
-        # Include prompt for video jobs
+
         if job.job_type == "video" and job.input_data:
             job_item["prompt"] = job.input_data.get("prompt")
         
-        # Include error message for failed jobs
+
         if job.status == "failed":
             job_item["error"] = job.error_message
         
-        # Include download URL for completed video jobs
+
         if job.status == "completed" and job.job_type == "video" and job.output_data and job.output_data.get("filename"):
             job_item["download_url"] = f"/gemini/download/{job.job_id}"
         
@@ -345,16 +322,11 @@ async def get_job_status(
     req: Request,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Get the status of a job.
-    Poll this endpoint until status is 'completed' or 'failed'.
-    For processing video jobs, this will check the Gemini API status and update the job.
-    Auth handled by AuthMiddleware - user in request.state.user
-    """
+    """Get job status and update if processing."""
     user = req.state.user
     query = select(GeminiJob).where(
         GeminiJob.job_id == job_id,
-        GeminiJob.user_id == user.id  # Integer FK comparison
+        GeminiJob.user_id == user.id
     )
     result = await db.execute(query)
     job = result.scalar_one_or_none()
@@ -365,7 +337,7 @@ async def get_job_status(
             detail="Job not found"
         )
     
-    # If job is processing and is a video job, check Gemini API status and update
+
     if job.status == "processing" and job.job_type == "video" and job.third_party_id:
         from services.gemini_job_worker import GeminiJobProcessor
         processor = GeminiJobProcessor()
@@ -382,7 +354,7 @@ async def get_job_status(
         "credits_remaining": user.credits
     }
     
-    # Include prompt for video jobs
+
     if job.job_type == "video" and job.input_data:
         response["prompt"] = job.input_data.get("prompt")
     
@@ -395,7 +367,7 @@ async def get_job_status(
     if job.status == "completed":
         response["completed_at"] = job.completed_at.isoformat() if job.completed_at else None
         
-        # Return generated prompt if available (for animation_prompt jobs)
+
         if job.output_data and "prompt" in job.output_data:
             response["prompt"] = job.output_data["prompt"]
     
@@ -412,19 +384,14 @@ async def download_video(
     req: Request,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Download a generated video.
-    Downloads from Gemini URL, streams to client, then deletes local file.
-    No permanent storage on server.
-    Auth handled by AuthMiddleware - user in request.state.user
-    """
+    """Stream video from Gemini to client."""
     user = req.state.user
     from fastapi.responses import StreamingResponse
     import httpx
     
     query = select(GeminiJob).where(
         GeminiJob.job_id == job_id,
-        GeminiJob.user_id == user.id,  # Integer FK comparison
+        GeminiJob.user_id == user.id,
         GeminiJob.job_type == "video"
     )
     result = await db.execute(query)
@@ -449,8 +416,7 @@ async def download_video(
             detail="No video URL available"
         )
     
-    # Stream video directly from Gemini URL to client
-    # No local file storage needed
+
     async def stream_video():
         try:
             async with httpx.AsyncClient(timeout=120.0, follow_redirects=True) as client:
@@ -460,7 +426,7 @@ async def download_video(
                         yield chunk
         except httpx.HTTPStatusError as e:
             if e.response.status_code in (401, 403, 404, 410):
-                # Mark job as expired
+
                 job.status = "expired"
                 await db.commit()
                 
@@ -493,16 +459,11 @@ async def cancel_job(
     req: Request,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Cancel a queued job.
-    Only jobs with status 'queued' can be cancelled.
-    Processing/completed/failed jobs cannot be cancelled.
-    Auth handled by AuthMiddleware - user in request.state.user
-    """
+    """Cancel a queued job."""
     user = req.state.user
     query = select(GeminiJob).where(
         GeminiJob.job_id == job_id,
-        GeminiJob.user_id == user.id  # Integer FK comparison
+        GeminiJob.user_id == user.id
     )
     result = await db.execute(query)
     job = result.scalar_one_or_none()
@@ -537,20 +498,12 @@ async def delete_job(
     req: Request,
     db: AsyncSession = Depends(get_db)
 ):
-    """
-    Soft delete a job with conditional credit refund.
-    
-    Refund policy:
-    - If queued: Refund 8 credits (10 cost - 2 penalty), soft delete job.
-    - If processing/completed/failed: Soft delete job (no refund).
-    Auth handled by AuthMiddleware - user in request.state.user
-    """
+    """Delete job with conditional credit refund."""
     user = req.state.user
     from services.db_service import QueryService
-    
     qs = QueryService(user, db)
     
-    # Get job (automatically filtered to user's job)
+
     job = await qs.select().execute_one(
         select(GeminiJob).where(GeminiJob.job_id == job_id)
     )
@@ -561,36 +514,32 @@ async def delete_job(
             detail="Job not found"
         )
     
-    # Implement credit refund via CreditTransactionManager
+
     refund_amount = 0
     message = "Job deleted"
     
-    # Determine refund based on job status
+
     if job.credits_reserved > 0 and not job.credits_refunded:
         from services.credit_service import CreditTransactionManager
         
         if not job.third_party_id:
-            # Job never started (pre-execution failure)
             refund_amount = job.credits_reserved
             refund_reason = "Job deleted before execution"
             
         elif job.status == "queued":
-            # Job queued - partial refund (2 credits cancellation fee)
             penalty = 2
             refund_amount = max(0, job.credits_reserved - penalty)
             refund_reason = f"Job cancelled while queued (penalty: {penalty} credits)"
             
         elif job.status in ["processing", "completed"]:
-            # No refund for started/completed jobs
             refund_amount = 0
             refund_reason = None
             
         elif job.status == "failed":
-            # Failed job - full refund
             refund_amount = job.credits_reserved
             refund_reason = "Job failed - full refund"
         
-        # Process refund if applicable
+
         if refund_amount > 0:
             try:
                 await CreditTransactionManager.add_credits(
@@ -616,7 +565,7 @@ async def delete_job(
                 logger.error(f"Failed to refund credits for job {job_id}: {e}")
                 message = "Job deleted (refund failed - contact support)"
     
-    # Soft delete the job
+
     deleted = await qs.delete().soft_delete_one(job)
     
     if not deleted:
@@ -635,7 +584,5 @@ async def delete_job(
 
 @router.get("/models")
 async def get_models():
-    """
-    Get available model names.
-    """
+    """Get available model names."""
     return {"models": MODELS}

run_credit_tests.py

@@ -1,61 +0,0 @@
-#!/usr/bin/env python3
-"""
-Run Credit Service Test Suite
-
-Runs all credit service tests and generates a coverage report.
-"""
-import sys
-import subprocess
-
-def run_tests():
-    """Run pytest for credit service tests."""
-    
-    print("=" * 70)
-    print("Running Credit Service Test Suite")
-    print("=" * 70)
-    print()
-    
-    test_files = [
-        "tests/test_credit_transaction_manager.py",
-        "tests/test_response_inspector.py",
-        "tests/test_credit_middleware_integration.py"
-    ]
-    
-    cmd = [
-        "pytest",
-        *test_files,
-        "-v",  # Verbose
-        "--tb=short",  # Short traceback
-        "--cov=services/credit_service",  # Coverage for credit service
-        "--cov-report=term-missing",  # Show missing lines
-        "--cov-report=html:htmlcov/credit_service",  # HTML report
-    ]
-    
-    print(f"Command: {' '.join(cmd)}")
-    print()
-    
-    try:
-        result = subprocess.run(cmd, check=False)
-        
-        print()
-        print("=" * 70)
-        if result.returncode == 0:
-            print("✅ All tests passed!")
-        else:
-            print("❌ Some tests failed!")
-        print("=" * 70)
-        print()
-        print("Coverage report generated at: htmlcov/credit_service/index.html")
-        
-        return result.returncode
-        
-    except FileNotFoundError:
-        print("❌ pytest not found. Install it with: pip install pytest pytest-asyncio pytest-cov")
-        return 1
-    except Exception as e:
-        print(f"❌ Error running tests: {e}")
-        return 1
-
-
-if __name__ == "__main__":
-    sys.exit(run_tests())

run_tests.sh

@@ -1,13 +0,0 @@
-#!/bin/bash
-# Test runner for DB Service
-
-export ADMIN_EMAILS="admin@example.com"
-export PYTHONPATH="$(pwd):$PYTHONPATH"
-
-echo "Running DB Service Tests..."
-echo "=============================="
-
-python -m pytest tests/test_db_service.py -v --tb=short
-
-echo ""
-echo "Test run complete!"

services/credit_service/middleware.py

@@ -1,10 +1,6 @@
 """
-Credit Middleware - Automatic request/response-based credit management.
-
-Intercepts requests to reserve credits and inspects responses to automatically
-confirm or refund based on operation success/failure.
-
-Application layer is completely unaware of credit management.
+Credit Middleware - Automatic credit management.
+Reserves credits on request, confirms/refunds based on response.
 """
 
 import logging
@@ -31,18 +27,9 @@ logger = logging.getLogger(__name__)
 
 class CreditMiddleware(BaseServiceMiddleware):
     """
-    Credit middleware with automatic request/response-based credit management.
-    
-    Application layer is completely unaware of credits.
-    Credits are reserved on request, confirmed/refunded based on response.
-    
-    Flow:
-    1. REQUEST PHASE: Reserve credits if endpoint requires them
-    2. APPLICATION: Process request (unaware of credits)
-    3. RESPONSE PHASE: Inspect response and confirm/refund credits
-    
-    NOTE: This middleware MUST run AFTER AuthMiddleware since it needs
-    the authenticated user from request.state.user
+    Credit middleware with automatic credit management.
+    Reserves credits on request, confirms/refunds based on response.
+    Must run after AuthMiddleware.
     """
     
     SERVICE_NAME = "credit"
@@ -50,22 +37,21 @@ class CreditMiddleware(BaseServiceMiddleware):
     async def dispatch(self, request: Request, call_next):
         """Process request through credit middleware."""
         
-        # Skip OPTIONS requests (CORS preflight)
+
         if request.method == "OPTIONS":
             return await call_next(request)
         
         path = request.url.path
         
-        # Get endpoint configuration
+
         config = CreditServiceConfig.get_config(path)
         credit_cost = config.get("cost", 0)
         endpoint_type = config.get("type", "free")
         
-        if credit_cost == 0:
-            # Free endpoint, no credit handling needed
+
             return await call_next(request)
         
-        # User must be authenticated (set by AuthMiddleware)
+
         user = getattr(request.state, 'user', None)
         if not user:
             return JSONResponse(
@@ -73,12 +59,9 @@ class CreditMiddleware(BaseServiceMiddleware):
                 content={"detail": "Authentication required for this endpoint"}
             )
         
-        # ===================================================================
-        # REQUEST PHASE: Reserve Credits
-        # ===================================================================
+
         async with async_session_maker() as db:
-            try:
-                # Reserve credits
+
                 transaction = await CreditTransactionManager.reserve_credits(
                     session=db,
                     user=user,
@@ -96,7 +79,7 @@ class CreditMiddleware(BaseServiceMiddleware):
                 
                 await db.commit()
                 
-                # Attach transaction info to request for response phase
+
                 request.state.credit_transaction_id = transaction.transaction_id
                 request.state.endpoint_type = endpoint_type
                 request.state.credit_cost = credit_cost
@@ -124,30 +107,24 @@ class CreditMiddleware(BaseServiceMiddleware):
                     content={"detail": "Failed to reserve credits"}
                 )
         
-        # ===================================================================
-        # CALL APPLICATION LAYER (completely unaware of credits)
-        # ===================================================================
+
         response = await call_next(request)
         
-        # ===================================================================
-        # RESPONSE PHASE: Confirm or Refund Based on Response
-        # ===================================================================
+
         transaction_id = getattr(request.state, 'credit_transaction_id', None)
-        if not transaction_id:
-            # No transaction to finalize (shouldn't happen, but be safe)
+
             return response
         
-        # We need to read the response body to inspect it
-        # This requires special handling to not consume the response
+
         response_body = b""
         async for chunk in response.body_iterator:
             response_body += chunk
         
-        # Parse response for inspection
+
         response_data = ResponseInspector.parse_response_body(response_body)
         inspector = ResponseInspector()
         
-        # Determine credit action based on response
+
         async with async_session_maker() as db:
             try:
                 should_confirm = inspector.should_confirm(
@@ -157,8 +134,7 @@ class CreditMiddleware(BaseServiceMiddleware):
                     response, endpoint_type, response_data
                 )
                 
-                if should_confirm:
-                    # Operation successful - confirm credits
+
                     await CreditTransactionManager.confirm_credits(
                         session=db,
                         transaction_id=transaction_id,
@@ -174,8 +150,7 @@ class CreditMiddleware(BaseServiceMiddleware):
                         f"Credits confirmed for {transaction_id} (success)"
                     )
                 
-                elif should_refund:
-                    # Operation failed - refund credits
+
                     reason = inspector.get_refund_reason(response, response_data)
                     await CreditTransactionManager.refund_credits(
                         session=db,
@@ -194,20 +169,16 @@ class CreditMiddleware(BaseServiceMiddleware):
                         f"Credits refunded for {transaction_id}: {reason}"
                     )
                 
-                else:
-                    # Keep reserved (async operation pending completion)
+
                     self.log_request(
                         request,
                         f"Credits kept reserved for {transaction_id} (async pending)"
                     )
                 
             except Exception as e:
-                logger.error(f"Response phase credit handling failed: {e}", exc_info=True)
-                # Don't fail the actual response, just log the error
-                # The transaction remains reserved and can be manually resolved
+
         
-        # Reconstruct response with original body
-        # This is necessary because we consumed the body_iterator above
+
         return Response(
             content=response_body,
             status_code=response.status_code,

test_token_expiry.py

@@ -1,106 +0,0 @@
-#!/usr/bin/env python3
-"""
-Simple JWT Token Expiry Test - Direct approach
-"""
-import os
-import jwt
-import time
-from datetime import datetime, timedelta
-from dotenv import load_dotenv
-
-# Load environment variables
-load_dotenv()
-
-def test_token_expiry():
-    """Test JWT token creation and expiry"""
-    
-    print("=" * 70)
-    print("JWT Token Expiry Test")
-    print("=" * 70)
-    
-    # Get environment variables
-    access_expiry_minutes = int(os.getenv("JWT_ACCESS_EXPIRY_MINUTES", "15"))
-    jwt_secret = os.getenv("JWT_SECRET")
-    jwt_algorithm = os.getenv("JWT_ALGORITHM", "HS256")
-    
-    print(f"\n📋 Current Configuration:")
-    print(f"   JWT_ACCESS_EXPIRY_MINUTES: {access_expiry_minutes} minute(s)")
-    print(f"   JWT_ALGORITHM: {jwt_algorithm}")
-    print(f"   JWT_SECRET: {'✅ Set' if jwt_secret else '❌ NOT SET'}")
-    
-    if not jwt_secret:
-        print("\n❌ ERROR: JWT_SECRET not set!")
-        return
-    
-    # Create token manually
-    print(f"\n🔐 Creating test token...")
-    now = datetime.utcnow()
-    expires_at = now + timedelta(minutes=access_expiry_minutes)
-    
-    payload = {
-        "sub": "test_user_123",
-        "email": "test@example.com",
-        "type": "access",
-        "tv": 1,
-        "iat": now,
-        "exp": expires_at
-    }
-    
-    token = jwt.encode(payload, jwt_secret, algorithm=jwt_algorithm)
-    print(f"   ✅ Token created")
-    print(f"   Issued at:  {now}")
-    print(f"   Expires at: {expires_at}")
-    print(f"   Token lifetime: {access_expiry_minutes} minute(s)")
-    
-    # Verify token is valid now
-    print(f"\n✅ Verifying token immediately...")
-    try:
-        decoded = jwt.decode(token, jwt_secret, algorithms=[jwt_algorithm])
-        print(f"   ✅ Token is valid")
-        print(f"   User: {decoded['sub']}")
-        print(f"   Email: {decoded['email']}")
-    except jwt.ExpiredSignatureError:
-        print(f"   ❌ Token already expired (shouldn't happen!)")
-        return
-    except Exception as e:
-        print(f"   ❌ Error: {e}")
-        return
-    
-    # If very short expiry, wait and test
-    if access_expiry_minutes <= 5:
-        wait_seconds = (access_expiry_minutes * 60) + 5
-        print(f"\n⏳ Waiting {wait_seconds} seconds for token to expire...")
-        print(f"   Token should expire at: {expires_at}")
-        
-        for i in range(wait_seconds):
-            remaining = wait_seconds - i
-            if remaining % 10 == 0 or remaining <= 10:
-                print(f"   ⏱️  {remaining} seconds remaining...")
-            time.sleep(1)
-        
-        print(f"\n🔍 Testing token after {wait_seconds} seconds...")
-        print(f"   Current time: {datetime.utcnow()}")
-        
-        try:
-            decoded = jwt.decode(token, jwt_secret, algorithms=[jwt_algorithm])
-            print(f"   ❌ Token STILL VALID (This is a problem!)")
-            print(f"   This means the token didn't expire as expected")
-        except jwt.ExpiredSignatureError:
-            print(f"   ✅ Token EXPIRED (This is correct!)")
-            print(f"   Token expiry is working properly")
-        except Exception as e:
-            print(f"   ⚠️  Error: {e}")
-    else:
-        print(f"\n💡 Token expiry is set to {access_expiry_minutes} minutes")
-        print(f"   This is too long to wait in this test")
-        print(f"   To test expiry quickly:")
-        print(f"   1. Set JWT_ACCESS_EXPIRY_MINUTES=1 in .env")
-        print(f"   2. Restart the server")
-        print(f"   3. Run this test again")
-    
-    print("\n" + "=" * 70)
-    print("Test Complete!")
-    print("=" * 70)
-
-if __name__ == "__main__":
-    test_token_expiry()

tests/CREDIT_TESTS_README.md

@@ -1,177 +0,0 @@
-# Credit Service Test Suite
-
-## Overview
-
-Comprehensive test suite for the middleware-centric credit service covering:
-- Transaction Manager operations
-- Response inspection logic  
-- Middleware integration
-- End-to-end credit flows
-
-## Test Files
-
-### 1. `test_credit_transaction_manager.py`
-Tests core credit transaction operations:
-- ✅ Reserve credits (success & insufficient funds)
-- ✅ Confirm credits
-- ✅ Refund credits
-- ✅ Add credits (purchases)
-- ✅ Balance verification
-- ✅ Transaction history queries
-- ✅ Full transaction flows (reserve→confirm, reserve→refund)
-
-**Coverage:** All `CreditTransactionManager` methods and error scenarios
-
-### 2. `test_response_inspector.py`
-Tests response analysis logic:
-- ✅ Sync endpoint success/failure detection
-- ✅ Async job creation handling
-- ✅ Async job status checks (queued, processing, completed, failed)
-- ✅ Refundable vs non-refundable error classification
-- ✅ Refund reason generation
-- ✅ JSON parsing utilities
-
-**Coverage:** All `ResponseInspector` methods and edge cases
-
-### 3. `test_credit_middleware_integration.py`
-Tests middleware end-to-end flow:
-- ✅ Free endpoint bypass
-- ✅ Authentication enforcement
-- ✅ Credit reservation on request
-- ✅ Insufficient credits rejection
-- ✅ Automatic confirmation on success
-- ✅ Automatic refund on failure
-- ✅ Async operation handling
-- ✅ Error handling & resilience
-
-**Coverage:** Complete middleware request/response cycle
-
-## Running Tests
-
-### Quick Run
-```bash
-python3 run_credit_tests.py
-```
-
-### Manual Run with Coverage
-```bash
-pytest tests/test_credit*.py -v --cov=services/credit_service --cov-report=html
-```
-
-### Run Specific Test File
-```bash
-pytest tests/test_credit_transaction_manager.py -v
-pytest tests/test_response_inspector.py -v
-pytest tests/test_credit_middleware_integration.py -v
-```
-
-### Run Specific Test
-```bash
-pytest tests/test_credit_transaction_manager.py::test_reserve_credits_success -v
-```
-
-## Test Coverage Goals
-
-| Component | Target Coverage | Status |
-|-----------|----------------|--------|
-| CreditTransactionManager | 90%+ | ✅ |
-| ResponseInspector | 95%+ | ✅ |
-| CreditMiddleware | 85%+ | ✅ |
-| Overall Credit Service | 90%+ | 🎯 |
-
-## Test Scenarios Covered
-
-### Happy Paths
-- [x] Successful credit reservation
-- [x] Successful credit confirmation
-- [x] Successful credit refund
-- [x] Successful credit purchase
-- [x] Sync operation success → confirm
-- [x] Async job completion → confirm
-
-### Error Paths
-- [x] Insufficient credits
-- [x] Transaction not found
-- [x] User not found
-- [x] Sync operation failure → refund
-- [x] Async job failure (refundable) → refund
-- [x] Async job failure (non-refundable) → keep deducted
-- [x] Database errors during operations
-- [x] Malformed responses
-
-### Edge Cases
-- [x] Exact balance reservation
-- [x] Free endpoint (cost=0)
-- [x] Unauthenticated requests  
-- [x] OPTIONS requests
-- [x] Missing status field in async response
-- [x] Response phase errors don't break actual response
-
-## Dependencies
-
-Install test dependencies:
-```bash
-pip install pytest pytest-asyncio pytest-cov aiosqlite
-```
-
-## Test Database
-
-Tests use in-memory SQLite database (`sqlite+aiosqlite:///:memory:`) for:
-- Fast execution
-- No side effects
-- Complete isolation
-- Automatic cleanup
-
-## Continuous Integration
-
-Add to CI pipeline:
-```yaml
-# .github/workflows/test.yml
-- name: Run Credit Service Tests
-  run: python3 run_credit_tests.py
-  
-- name: Upload Coverage
-  uses: codecov/codecov-action@v3
-  with:
-    files: ./htmlcov/credit_service/coverage.xml
-```
-
-## Future Test Additions
-
-- [ ] Concurrent operation tests (race conditions)
-- [ ] Load testing (many simultaneous requests)
-- [ ] API endpoint tests (/credits/transactions, /credits/balance/verify)
-- [ ] Payment integration tests
-- [ ] Job lifecycle integration tests
-- [ ] Performance benchmarks
-
-## Test Conventions
-
-- **Fixtures**: Defined at file level, reusable across tests
-- **Naming**: `test_<component>_<scenario>` format
-- **Assertions**: Multiple assertions per test acceptable for related checks
-- **Async**: All database tests use `@pytest.mark.asyncio`
-- **Mocking**: Use `unittest.mock` for external dependencies
-- **Cleanup**: Automatic via fixtures, no manual teardown needed
-
-## Troubleshooting
-
-**Issue:** `ModuleNotFoundError: No module named 'pytest'`  
-**Fix:** `pip install pytest pytest-asyncio`
-
-**Issue:** Tests fail with database errors  
-**Fix:** Ensure `aiosqlite` is installed: `pip install aiosqlite`
-
-**Issue:** Coverage report not generated  
-**Fix:** Install coverage tools: `pip install pytest-cov`
-
-**Issue:** Import errors for credit service modules  
-**Fix:** Run tests from project root directory
-
-## Maintenance
-
-When adding new credit service features:
-1. Add tests to appropriate test file
-2. Run full test suite to ensure no regressions
-3. Update coverage target if needed
-4. Document new test scenarios in this README