diff --git a/.env.local b/.env.local new file mode 100644 index 0000000..3725b4f --- /dev/null +++ b/.env.local @@ -0,0 +1,106 @@ +# ============================================================================= +# Local Development Environment Variables for Accessible Video Platform +# ============================================================================= +# IMPORTANT: This file is for local Docker-based development only +# Usage: ./scripts/run-local.sh (backend) + npm run dev (frontend) +# ============================================================================= + +# ----------------------------------------------------------------------------- +# App Configuration +# ----------------------------------------------------------------------------- +APP_ENV=dev +API_BASE_URL=http://localhost:8000 + +# ----------------------------------------------------------------------------- +# Authentication & Security +# ----------------------------------------------------------------------------- +# Using same JWT secret as production (shared between environments) +JWT_SECRET=CHANGE_ME_TO_SECURE_RANDOM_64_CHAR_STRING +JWT_ALG=HS256 +JWT_ACCESS_TTL_MIN=240 +JWT_REFRESH_TTL_DAYS=7 + +# Local development cookie settings (HTTP, not HTTPS) +COOKIE_DOMAIN=localhost +COOKIE_SECURE=false +COOKIE_SAMESITE=Lax + +# ----------------------------------------------------------------------------- +# MongoDB Configuration +# ----------------------------------------------------------------------------- +# MongoDB runs without authentication in the internal Docker network +MONGODB_DB=accessible_video + +# Note: MongoDB connection string is auto-constructed in docker-compose.yml +# Format: mongodb://mongodb:27017/${MONGODB_DB} + +# ----------------------------------------------------------------------------- +# Redis Configuration +# ----------------------------------------------------------------------------- +# Redis runs without authentication in the internal Docker network +# No configuration needed - connection strings in docker-compose.yml +# REDIS_URL=redis://redis:6379/0 + +# ----------------------------------------------------------------------------- +# Google Cloud Platform (GCP) +# ----------------------------------------------------------------------------- +GCP_PROJECT_ID=optical-414516 +GCS_BUCKET=accessible-video + +# GCP credentials file will be mounted as a volume +# Location inside container: /secrets/gcp-credentials.json +# Local source: ./secrets/gcp-credentials.json + +# ----------------------------------------------------------------------------- +# AI Services +# ----------------------------------------------------------------------------- +# Using same API keys as production +GEMINI_API_KEY=AIzaSyAuuVGcvqfoP7pqX-YwieGszPsNSeAft-0 + +# Google Cloud Translate (Optional - for translation features) +TRANSLATE_API_KEY= + +# ElevenLabs TTS (Optional - for text-to-speech) +ELEVENLABS_API_KEY= + +# ----------------------------------------------------------------------------- +# Email Configuration (SendGrid) +# ----------------------------------------------------------------------------- +# Optional: Leave empty to disable email sending in local dev +SENDGRID_API_KEY= + +# Email sender address (local development) +EMAIL_FROM=noreply@localhost + +# Client-facing URL (used in emails) - points to local frontend +CLIENT_BASE_URL=http://localhost:6001/video-accessibility + +# ----------------------------------------------------------------------------- +# Microsoft Authentication (Azure AD) +# ----------------------------------------------------------------------------- +AZURE_CLIENT_ID=9079054c-9620-4757-a256-23413042f1ef +AZURE_AUTHORITY=https://login.microsoftonline.com/e519c2e6-bc6d-4fdf-8d9c-923c2f002385 +AZURE_REDIRECT_URI=http://localhost:6001/video-accessibility/ + +# ----------------------------------------------------------------------------- +# CORS Configuration +# ----------------------------------------------------------------------------- +# Comma-separated list of allowed origins for local development +CORS_ORIGINS=http://localhost:6001,http://localhost:5173,http://localhost:3000 + +# ----------------------------------------------------------------------------- +# Observability & Monitoring (Optional) +# ----------------------------------------------------------------------------- +# Disabled for local development +SENTRY_DSN= +OTEL_EXPORTER_OTLP_ENDPOINT= + +# ============================================================================= +# LOCAL DEVELOPMENT NOTES +# ============================================================================= +# - Backend services run in Docker: API (port 8003), Worker, MongoDB, Redis +# - Frontend runs via npm: http://localhost:6001/video-accessibility +# - MongoDB and Redis data persists in Docker volumes +# - Same GCP credentials and API keys as production +# - Cookies work on localhost (not secure, for dev only) +# ============================================================================= diff --git a/.env.production b/.env.production index 9f8f20f..4eff571 100644 --- a/.env.production +++ b/.env.production @@ -74,6 +74,19 @@ EMAIL_FROM=noreply@ai-sandbox.oliver.solutions # Client-facing URL (used in emails) CLIENT_BASE_URL=https://ai-sandbox.oliver.solutions/video-accessibility +# ----------------------------------------------------------------------------- +# Microsoft Authentication (Azure AD) +# ----------------------------------------------------------------------------- +AZURE_CLIENT_ID=9079054c-9620-4757-a256-23413042f1ef +AZURE_AUTHORITY=https://login.microsoftonline.com/e519c2e6-bc6d-4fdf-8d9c-923c2f002385 +AZURE_REDIRECT_URI=https://ai-sandbox.oliver.solutions/video-accessibility/ + +# ----------------------------------------------------------------------------- +# CORS Configuration +# ----------------------------------------------------------------------------- +# Comma-separated list of allowed origins +CORS_ORIGINS=https://ai-sandbox.oliver.solutions + # ----------------------------------------------------------------------------- # Observability & Monitoring (Optional) # ----------------------------------------------------------------------------- diff --git a/README.md b/README.md index e3de007..9e19004 100644 --- a/README.md +++ b/README.md @@ -74,49 +74,105 @@ Storage Pro + Validation Review Translate Speech Approval D ### Prerequisites - **Python 3.11+** (backend development) -- **Node.js 18+** (frontend development) -- **Poetry** (Python dependency management) -- **Docker & Docker Compose** (local development) -- **Google Cloud Project** with APIs enabled -- **MongoDB Atlas** (recommended) or local MongoDB -- **Redis** (included in docker-compose) +- **Node.js 18+** (frontend development) +- **Docker & Docker Compose** (required for local development) +- **Google Cloud Project** with APIs enabled (for video processing) -### Quick Start with Docker 🐳 +### 🐳 Local Development with Docker (Recommended) + +This is the recommended approach for local development. Backend services run in Docker containers while the frontend runs via Vite dev server for fast hot-reload. + +#### Initial Setup ```bash -# 1. Clone and setup +# 1. Clone the repository git clone cd video_accessibility -# 2. Configure environment (copy and edit sample files) -cp backend/.env.example backend/.env -cp frontend/.env.example frontend/.env +# 2. Copy and configure environment files +cp .env.prod.example .env.local +# Edit .env.local with your API keys and settings -# 3. Start all services -docker-compose up -d +# 3. Set up frontend environment +cp frontend/.env.example frontend/.env.local +# The defaults should work for local development -# 4. Access the application -# Frontend: http://localhost:5173 -# Backend API: http://localhost:8000 -# API Docs: http://localhost:8000/docs +# 4. Ensure GCP credentials are in place +# Copy your GCP service account JSON to: ./secrets/gcp-credentials.json ``` -### Local Development Setup +#### Starting the Development Environment + +**Step 1: Start Backend Services (Docker)** ```bash -# Backend +# Start API, Worker, MongoDB, and Redis in Docker +./scripts/run-local.sh + +# Services will be available at: +# - API: http://localhost:8003 +# - API Docs: http://localhost:8003/docs +# - MongoDB: mongodb://localhost:27017 +# - Redis: redis://localhost:6379 +``` + +**Step 2: Start Frontend (Vite Dev Server)** +```bash +# In a separate terminal +cd frontend +npm install # First time only +npm run dev + +# Frontend will be available at: +# - Application: http://localhost:6001/video-accessibility +``` + +#### Useful Commands +```bash +# View logs +docker compose logs -f api # API logs +docker compose logs -f worker # Worker logs +docker compose logs -f # All logs + +# Restart a service +docker compose restart api +docker compose restart worker + +# Rebuild and restart (after code changes) +./scripts/run-local.sh --rebuild + +# Stop all services +./scripts/run-local.sh --stop +# or +docker compose down +``` + +### Alternative: Native Development (Without Docker) + +For development without Docker, you'll need to run each service manually: + +```bash +# Terminal 1: MongoDB +mongod --dbpath ./data/db + +# Terminal 2: Redis +redis-server + +# Terminal 3: Backend API cd backend poetry install poetry run uvicorn app.main:app --reload --port 8000 -# Frontend (new terminal) +# Terminal 4: Celery Worker +cd backend +poetry run celery -A app.tasks worker --loglevel=info + +# Terminal 5: Frontend cd frontend npm install npm run dev - -# Worker (new terminal) -cd backend -poetry run celery -A app.tasks worker --loglevel=info ``` +**Note**: The Docker approach is strongly recommended as it ensures consistency and simplifies setup. + ### Testing & Quality ```bash # Backend tests + linting @@ -172,8 +228,18 @@ video_accessibility/ # Root monorepo │ │ ├── hooks/ # Custom React hooks │ │ └── types/ # TypeScript definitions │ ├── tests/ # Unit + E2E tests +│ ├── .env.local # Local development config │ └── Dockerfile # Container configuration -├── docker-compose.yml # Local development stack +├── scripts/ +│ ├── run-local.sh # Local development startup +│ ├── deploy.sh # Production deployment +│ ├── full-deploy.sh # Full production rebuild +│ └── build-frontend.sh # Frontend build script +├── docker-compose.yml # Base Docker configuration +├── docker-compose.local.yml # Local development overrides +├── docker-compose.prod.yml # Production overrides +├── .env.local # Local environment variables +├── .env.production # Production environment variables ├── CLAUDE.md # Development guidelines └── video_accessibility_development_plan.txt # Complete specification ``` diff --git a/backend/app/api/v1/routes_admin.py b/backend/app/api/v1/routes_admin.py index e6c6317..4bb77ec 100644 --- a/backend/app/api/v1/routes_admin.py +++ b/backend/app/api/v1/routes_admin.py @@ -60,6 +60,7 @@ async def list_users( email=user_doc["email"], full_name=user_doc["full_name"], role=user_doc["role"], + auth_provider=user_doc.get("auth_provider", "local"), is_active=user_doc["is_active"], created_at=user_doc.get("created_at", datetime.utcnow()).isoformat() )) @@ -91,6 +92,7 @@ async def get_user( email=user_doc["email"], full_name=user_doc["full_name"], role=user_doc["role"], + auth_provider=user_doc.get("auth_provider", "local"), is_active=user_doc["is_active"], created_at=user_doc.get("created_at", datetime.utcnow()).isoformat() ) @@ -119,6 +121,7 @@ async def create_user( "hashed_password": get_password_hash(user_data.password), "full_name": user_data.full_name, "role": user_data.role.value, + "auth_provider": "local", "is_active": True, "created_at": datetime.utcnow(), "updated_at": datetime.utcnow() @@ -130,12 +133,13 @@ async def create_user( app_metrics.record_auth_attempt("user_created", user_data.role.value) logger.info(f"Admin {current_user.id} created user {user_id} with role {user_data.role.value}") - + return UserResponse( id=user_id, email=user_data.email, full_name=user_data.full_name, role=user_data.role, + auth_provider="local", is_active=True, created_at=user_doc["created_at"].isoformat() ) @@ -186,12 +190,13 @@ async def update_user( ) logger.info(f"Admin {current_user.id} updated user {user_id}") - + return UserResponse( id=str(result["_id"]), email=result["email"], full_name=result["full_name"], role=result["role"], + auth_provider=result.get("auth_provider", "local"), is_active=result["is_active"], created_at=result.get("created_at", datetime.utcnow()).isoformat() ) diff --git a/backend/app/api/v1/routes_auth.py b/backend/app/api/v1/routes_auth.py index 0ee1b0f..5ee77b9 100644 --- a/backend/app/api/v1/routes_auth.py +++ b/backend/app/api/v1/routes_auth.py @@ -1,3 +1,4 @@ +from datetime import datetime from fastapi import APIRouter, Depends, HTTPException, Request, Response, status from fastapi.security import HTTPBearer from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase @@ -10,8 +11,20 @@ from ...core.security import ( decode_token, verify_password, ) -from ...models.user import User -from ...schemas.auth import LoginRequest, LoginResponse, LogoutResponse, RefreshResponse +from ...models.user import User, AuthProvider, UserRole +from ...schemas.auth import ( + LoginRequest, + LoginResponse, + LogoutResponse, + RefreshResponse, + MicrosoftLoginRequest, + MicrosoftLoginResponse, +) +from ...services.microsoft_auth import ( + get_microsoft_auth_service, + MicrosoftTokenValidationError, + MicrosoftAuthError, +) router = APIRouter(prefix="/auth", tags=["auth"]) security = HTTPBearer() @@ -41,8 +54,15 @@ async def login( user = User(**user_doc) + # Check if user uses Microsoft authentication + if user.auth_provider == AuthProvider.MICROSOFT: + raise HTTPException( + status_code=status.HTTP_400_BAD_REQUEST, + detail="This account uses Microsoft authentication. Please sign in with Microsoft.", + ) + # Verify password - if not verify_password(login_data.password, user.hashed_password): + if not user.hashed_password or not verify_password(login_data.password, user.hashed_password): raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Incorrect email or password", @@ -80,6 +100,120 @@ async def login( client.close() +@router.post("/microsoft", response_model=MicrosoftLoginResponse) +async def microsoft_login( + login_data: MicrosoftLoginRequest, + response: Response, +): + """Authenticate user with Microsoft ID token. + + This endpoint validates the Microsoft ID token, finds or creates the user, + and returns JWT tokens for API access. + """ + print(f"MICROSOFT LOGIN: Starting Microsoft authentication") + + # Create database connection + client = AsyncIOMotorClient(settings.mongodb_uri) + db = client[settings.mongodb_db] + + try: + # Validate Microsoft token + microsoft_auth = get_microsoft_auth_service() + try: + user_info = microsoft_auth.validate_token(login_data.id_token) + print(f"MICROSOFT LOGIN: Token validated for {user_info.email}") + except MicrosoftTokenValidationError as e: + print(f"MICROSOFT LOGIN ERROR: Token validation failed: {e}") + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail=f"Microsoft authentication failed: {str(e)}", + ) + except MicrosoftAuthError as e: + print(f"MICROSOFT LOGIN ERROR: Authentication error: {e}") + raise HTTPException( + status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, + detail="Microsoft authentication service error", + ) + + # Find or create user + user_doc = await db.users.find_one({"email": user_info.email}) + + if user_doc: + # User exists + user = User(**user_doc) + print(f"MICROSOFT LOGIN: Existing user found: {user.id}") + + # Update auth_provider if user is switching from local to Microsoft + if user.auth_provider == AuthProvider.LOCAL: + print(f"MICROSOFT LOGIN: Updating user to Microsoft auth provider") + await db.users.update_one( + {"_id": user_doc["_id"]}, + { + "$set": { + "auth_provider": AuthProvider.MICROSOFT.value, + "updated_at": datetime.utcnow() + } + } + ) + user.auth_provider = AuthProvider.MICROSOFT + + else: + # Create new user + print(f"MICROSOFT LOGIN: Creating new user for {user_info.email}") + new_user_id = f"ms-{user_info.sub[:20]}" # Use Microsoft sub as ID + new_user = { + "_id": new_user_id, + "email": user_info.email, + "full_name": user_info.name, + "hashed_password": None, # No password for Microsoft users + "role": UserRole.CLIENT.value, + "auth_provider": AuthProvider.MICROSOFT.value, + "is_active": True, + "created_at": datetime.utcnow(), + "updated_at": datetime.utcnow(), + } + + await db.users.insert_one(new_user) + user = User(**new_user) + print(f"MICROSOFT LOGIN: New user created: {user.id}") + + # Check if user is active + if not user.is_active: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="User account is disabled", + ) + + # Create JWT tokens + access_token = create_access_token(subject=str(user.id)) + refresh_token = create_refresh_token(subject=str(user.id)) + + # Set refresh token as HttpOnly cookie + response.set_cookie( + key="refresh_token", + value=refresh_token, + httponly=True, + secure=settings.cookie_secure, + samesite=settings.cookie_samesite, + domain=settings.cookie_domain if settings.app_env == "prod" else None, + max_age=settings.jwt_refresh_ttl_days * 24 * 60 * 60, + ) + + print(f"MICROSOFT LOGIN: Authentication successful for {user.email}") + return MicrosoftLoginResponse( + access_token=access_token, + user_id=str(user.id), + role=user.role if isinstance(user.role, str) else user.role.value, + email=user.email, + full_name=user.full_name, + auth_provider=user.auth_provider, + ) + + finally: + # Close database connection + client.close() + + @router.post("/refresh", response_model=RefreshResponse) async def refresh_token( request: Request, diff --git a/backend/app/core/config.py b/backend/app/core/config.py index 5f6397b..2b82d0b 100644 --- a/backend/app/core/config.py +++ b/backend/app/core/config.py @@ -58,12 +58,22 @@ class Settings(BaseSettings): email_from: str client_base_url: str + # Microsoft Authentication (Azure AD) + azure_client_id: str = "" + azure_authority: str = "" + azure_redirect_uri: str = "" + # Observability sentry_dsn: str = "" otel_exporter_otlp_endpoint: str = "" - # CORS - cors_origins: list[str] = ["http://localhost:5173", "http://localhost:5174", "http://localhost:3000"] + # CORS - comma-separated list of allowed origins + cors_origins: str = "http://localhost:5173,http://localhost:5174,http://localhost:3000,http://localhost:6001" + + @property + def cors_origins_list(self) -> list[str]: + """Parse CORS origins from comma-separated string to list.""" + return [origin.strip() for origin in self.cors_origins.split(",") if origin.strip()] class Config: env_file = ".env" diff --git a/backend/app/main.py b/backend/app/main.py index ba7f33c..ad3324b 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -104,7 +104,7 @@ app = FastAPI( # CORS middleware app.add_middleware( CORSMiddleware, - allow_origins=settings.cors_origins, + allow_origins=settings.cors_origins_list, allow_credentials=True, allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"], allow_headers=["*"], @@ -132,14 +132,14 @@ async def cors_error_handler(request, call_next): # Always add CORS headers for allowed origins origin = request.headers.get("origin") - if origin and origin in settings.cors_origins: + if origin and origin in settings.cors_origins_list: response.headers["access-control-allow-origin"] = origin response.headers["access-control-allow-credentials"] = "true" # Add other necessary CORS headers for error responses if response.status_code >= 400: response.headers["access-control-allow-methods"] = "GET, POST, PUT, PATCH, DELETE" response.headers["access-control-allow-headers"] = "*" - + return response # Global exception handler to ensure CORS headers on all errors @@ -153,12 +153,12 @@ async def http_exception_handler(request: Request, exc: HTTPException): # Add CORS headers origin = request.headers.get("origin") - if origin and origin in settings.cors_origins: + if origin and origin in settings.cors_origins_list: response.headers["access-control-allow-origin"] = origin response.headers["access-control-allow-credentials"] = "true" response.headers["access-control-allow-methods"] = "GET, POST, PUT, PATCH, DELETE" response.headers["access-control-allow-headers"] = "*" - + return response # Global exception handler for validation errors @@ -172,7 +172,7 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE # Add CORS headers origin = request.headers.get("origin") - if origin and origin in settings.cors_origins: + if origin and origin in settings.cors_origins_list: response.headers["access-control-allow-origin"] = origin response.headers["access-control-allow-credentials"] = "true" response.headers["access-control-allow-methods"] = "GET, POST, PUT, PATCH, DELETE" @@ -204,7 +204,7 @@ async def general_exception_handler(request: Request, exc: Exception): # Add CORS headers origin = request.headers.get("origin") - if origin and origin in settings.cors_origins: + if origin and origin in settings.cors_origins_list: response.headers["access-control-allow-origin"] = origin response.headers["access-control-allow-credentials"] = "true" diff --git a/backend/app/migrations/scripts/migration_2025-01-10-000000_add_auth_provider.py b/backend/app/migrations/scripts/migration_2025-01-10-000000_add_auth_provider.py new file mode 100644 index 0000000..8f13597 --- /dev/null +++ b/backend/app/migrations/scripts/migration_2025-01-10-000000_add_auth_provider.py @@ -0,0 +1,48 @@ +"""Add auth_provider field to users collection.""" + +from app.migrations.migrator import Migration + + +class Migration(Migration): + """Add auth_provider field to support Microsoft authentication.""" + + def __init__(self): + super().__init__() + self.version = "2025-01-10-000000" + self.description = "Add auth_provider field to users collection" + + async def up(self) -> None: + """Add auth_provider field to all users.""" + + # Add auth_provider field to all existing users (default to 'local') + result = await self.db.users.update_many( + {"auth_provider": {"$exists": False}}, + {"$set": {"auth_provider": "local"}} + ) + + print(f"✅ Updated {result.modified_count} users with auth_provider='local'") + + # Create index on auth_provider for faster queries + await self.db.users.create_index([("auth_provider", 1)]) + print(f"✅ Created index on auth_provider field") + + print(f"✅ Applied migration {self.version}: {self.description}") + + async def down(self) -> None: + """Remove auth_provider field from all users.""" + + # Drop the index + try: + await self.db.users.drop_index("auth_provider_1") + print(f"✅ Dropped index on auth_provider field") + except Exception as e: + print(f"⚠️ Could not drop index: {e}") + + # Remove auth_provider field from all users + result = await self.db.users.update_many( + {}, + {"$unset": {"auth_provider": ""}} + ) + + print(f"✅ Removed auth_provider field from {result.modified_count} users") + print(f"⚠️ Rolled back migration {self.version}: {self.description}") diff --git a/backend/app/models/user.py b/backend/app/models/user.py index a3c6266..22a8cbc 100644 --- a/backend/app/models/user.py +++ b/backend/app/models/user.py @@ -24,12 +24,18 @@ class UserRole(str, Enum): ADMIN = "admin" +class AuthProvider(str, Enum): + LOCAL = "local" + MICROSOFT = "microsoft" + + class User(BaseModel): id: Optional[PyObjectId] = Field(None, alias="_id") email: EmailStr - hashed_password: str + hashed_password: Optional[str] = None # Optional for Microsoft users full_name: str role: UserRole = UserRole.CLIENT + auth_provider: AuthProvider = AuthProvider.LOCAL is_active: bool = True created_at: Optional[datetime] = None updated_at: Optional[datetime] = None diff --git a/backend/app/schemas/auth.py b/backend/app/schemas/auth.py index de0d77b..11e6e1a 100644 --- a/backend/app/schemas/auth.py +++ b/backend/app/schemas/auth.py @@ -1,6 +1,6 @@ from typing import Optional from pydantic import BaseModel, EmailStr -from ..models.user import UserRole +from ..models.user import UserRole, AuthProvider class LoginRequest(BaseModel): @@ -15,6 +15,22 @@ class LoginResponse(BaseModel): role: str +class MicrosoftLoginRequest(BaseModel): + """Request schema for Microsoft authentication.""" + id_token: str + + +class MicrosoftLoginResponse(BaseModel): + """Response schema for Microsoft authentication.""" + access_token: str + token_type: str = "bearer" + user_id: str + role: str + email: str + full_name: str + auth_provider: AuthProvider + + class RefreshResponse(BaseModel): access_token: str token_type: str = "bearer" @@ -34,6 +50,7 @@ class UserResponse(BaseModel): email: EmailStr full_name: str role: UserRole + auth_provider: AuthProvider is_active: bool created_at: Optional[str] = None diff --git a/backend/app/services/microsoft_auth.py b/backend/app/services/microsoft_auth.py new file mode 100644 index 0000000..8a4eaf4 --- /dev/null +++ b/backend/app/services/microsoft_auth.py @@ -0,0 +1,220 @@ +"""Microsoft Authentication Service + +Validates Microsoft ID tokens and extracts user information. +""" +import time +from typing import Dict, Optional +import requests +from jose import jwt, JWTError +from jose.exceptions import JWKError +from pydantic import BaseModel, EmailStr + +from ..core.config import settings +from ..core.logging import get_logger + +logger = get_logger(__name__) + + +class MicrosoftUserInfo(BaseModel): + """User information extracted from Microsoft ID token.""" + email: EmailStr + name: str + sub: str # Microsoft user ID + tid: str # Tenant ID + email_verified: bool = True + + +class MicrosoftAuthError(Exception): + """Base exception for Microsoft authentication errors.""" + pass + + +class MicrosoftTokenValidationError(MicrosoftAuthError): + """Raised when token validation fails.""" + pass + + +class MicrosoftAuthService: + """Service for Microsoft authentication operations.""" + + def __init__(self): + self.client_id = settings.azure_client_id + self.authority = settings.azure_authority + + # Extract tenant ID from authority URL + # Format: https://login.microsoftonline.com/{tenant_id} + self.tenant_id = self.authority.rstrip('/').split('/')[-1] + + # Microsoft's OpenID configuration endpoint + self.openid_config_url = f"{self.authority}/v2.0/.well-known/openid-configuration" + + # Cache for JWKS (public keys) + self._jwks_cache: Optional[Dict] = None + self._jwks_cache_time: float = 0 + self._jwks_cache_ttl: int = 3600 # Cache for 1 hour + + def _get_openid_config(self) -> Dict: + """Fetch OpenID Connect configuration from Microsoft.""" + try: + response = requests.get(self.openid_config_url, timeout=10) + response.raise_for_status() + return response.json() + except requests.RequestException as e: + logger.error(f"Failed to fetch OpenID configuration: {e}") + raise MicrosoftAuthError("Failed to fetch Microsoft authentication configuration") + + def _get_jwks(self, force_refresh: bool = False) -> Dict: + """Fetch JSON Web Key Set (JWKS) from Microsoft. + + Args: + force_refresh: Force refresh even if cache is valid + + Returns: + JWKS dictionary with public keys + """ + # Check cache + current_time = time.time() + if (not force_refresh and + self._jwks_cache and + (current_time - self._jwks_cache_time) < self._jwks_cache_ttl): + return self._jwks_cache + + try: + # Get JWKS URI from OpenID configuration + config = self._get_openid_config() + jwks_uri = config.get('jwks_uri') + + if not jwks_uri: + raise MicrosoftAuthError("JWKS URI not found in OpenID configuration") + + # Fetch JWKS + response = requests.get(jwks_uri, timeout=10) + response.raise_for_status() + jwks = response.json() + + # Update cache + self._jwks_cache = jwks + self._jwks_cache_time = current_time + + return jwks + + except requests.RequestException as e: + logger.error(f"Failed to fetch JWKS: {e}") + raise MicrosoftAuthError("Failed to fetch Microsoft public keys") + + def validate_token(self, id_token: str) -> MicrosoftUserInfo: + """Validate Microsoft ID token and extract user information. + + Args: + id_token: Microsoft ID token string + + Returns: + MicrosoftUserInfo with validated user data + + Raises: + MicrosoftTokenValidationError: If token validation fails + """ + try: + # Get JWKS for signature verification + jwks = self._get_jwks() + + # Decode token header to get key ID (kid) + unverified_header = jwt.get_unverified_header(id_token) + kid = unverified_header.get('kid') + + if not kid: + raise MicrosoftTokenValidationError("Token header missing 'kid' claim") + + # Find the matching key in JWKS + rsa_key = None + for key in jwks.get('keys', []): + if key.get('kid') == kid: + rsa_key = { + 'kty': key['kty'], + 'kid': key['kid'], + 'use': key.get('use'), + 'n': key['n'], + 'e': key['e'] + } + break + + if not rsa_key: + logger.warning(f"Key ID {kid} not found in JWKS, refreshing cache") + # Try refreshing JWKS cache (keys might have been rotated) + jwks = self._get_jwks(force_refresh=True) + for key in jwks.get('keys', []): + if key.get('kid') == kid: + rsa_key = { + 'kty': key['kty'], + 'kid': key['kid'], + 'use': key.get('use'), + 'n': key['n'], + 'e': key['e'] + } + break + + if not rsa_key: + raise MicrosoftTokenValidationError(f"Unable to find key with ID: {kid}") + + # Validate token signature and claims + try: + payload = jwt.decode( + id_token, + rsa_key, + algorithms=['RS256'], + audience=self.client_id, + issuer=f"https://login.microsoftonline.com/{self.tenant_id}/v2.0" + ) + except JWTError as e: + raise MicrosoftTokenValidationError(f"Token validation failed: {str(e)}") + + # Extract required claims + email = payload.get('email') or payload.get('preferred_username') + if not email: + raise MicrosoftTokenValidationError("Token missing email claim") + + name = payload.get('name') + if not name: + # Fallback to email if name not provided + name = email.split('@')[0] + + sub = payload.get('sub') + if not sub: + raise MicrosoftTokenValidationError("Token missing 'sub' claim") + + tid = payload.get('tid') + if not tid: + raise MicrosoftTokenValidationError("Token missing 'tid' claim") + + # Check if email is verified (Microsoft tokens are considered verified) + email_verified = payload.get('email_verified', True) + + # Create user info object + user_info = MicrosoftUserInfo( + email=email, + name=name, + sub=sub, + tid=tid, + email_verified=email_verified + ) + + logger.info(f"Successfully validated Microsoft token for user: {email}") + return user_info + + except JWKError as e: + logger.error(f"JWK error during token validation: {e}") + raise MicrosoftTokenValidationError(f"Key processing error: {str(e)}") + except Exception as e: + if isinstance(e, (MicrosoftAuthError, MicrosoftTokenValidationError)): + raise + logger.error(f"Unexpected error during token validation: {e}") + raise MicrosoftTokenValidationError(f"Token validation failed: {str(e)}") + + +# Singleton instance +microsoft_auth_service = MicrosoftAuthService() + + +def get_microsoft_auth_service() -> MicrosoftAuthService: + """Get Microsoft authentication service instance.""" + return microsoft_auth_service diff --git a/docker-compose.local.yml b/docker-compose.local.yml new file mode 100644 index 0000000..03b38ff --- /dev/null +++ b/docker-compose.local.yml @@ -0,0 +1,69 @@ +# ============================================================================= +# Docker Compose Local Development Overrides +# ============================================================================= +# Usage: docker compose -f docker-compose.yml -f docker-compose.local.yml up -d +# Or use: ./scripts/run-local.sh +# ============================================================================= + +version: '3.8' + +services: + # --------------------------------------------------------------------------- + # MongoDB - Local Development Settings + # --------------------------------------------------------------------------- + mongodb: + # No resource limits for local development + # Expose port for direct access (optional, for debugging with MongoDB Compass) + ports: + - "27017:27017" + + # --------------------------------------------------------------------------- + # Redis - Local Development Settings + # --------------------------------------------------------------------------- + redis: + # No resource limits for local development + # Expose port for direct access (optional, for debugging with Redis CLI) + ports: + - "6379:6379" + + # --------------------------------------------------------------------------- + # API - Local Development Settings + # --------------------------------------------------------------------------- + api: + # No resource limits for local development + # Build without cache for fresh builds + build: + context: ./backend + dockerfile: Dockerfile + target: api + # Optional: Uncomment to disable cache during development + # args: + # - BUILDKIT_INLINE_CACHE=0 + + # --------------------------------------------------------------------------- + # Worker - Local Development Settings + # --------------------------------------------------------------------------- + worker: + # No resource limits for local development + # Build without cache for fresh builds + build: + context: ./backend + dockerfile: Dockerfile + target: worker + # Optional: Uncomment to disable cache during development + # args: + # - BUILDKIT_INLINE_CACHE=0 + +# ============================================================================= +# LOCAL DEVELOPMENT NOTES +# ============================================================================= +# This override file: +# - Removes production resource limits +# - Exposes MongoDB (27017) and Redis (6379) ports for local tools +# - Keeps all volume mounts for data persistence +# - Uses same environment variables from .env.local +# +# To start: ./scripts/run-local.sh +# To stop: docker compose down +# To view logs: docker compose logs -f [service] +# ============================================================================= diff --git a/docs/video accessibility technical documentation 2025-09-09.pdf b/docs/video accessibility technical documentation 2025-09-09.pdf new file mode 100644 index 0000000..70c5498 Binary files /dev/null and b/docs/video accessibility technical documentation 2025-09-09.pdf differ diff --git a/docs/video_accessibility_technical_documentation_v2.md b/docs/video_accessibility_technical_documentation_v2.md new file mode 100644 index 0000000..4ce2536 --- /dev/null +++ b/docs/video_accessibility_technical_documentation_v2.md @@ -0,0 +1,2631 @@ +# Accessible Video Processing Platform - Technical Documentation v2.0 + +**Document Version:** 2.0 +**Last Updated:** October 9, 2025 +**System Version:** 1.0.0 +**Author:** Technical Documentation Team + +--- + +## Table of Contents + +1. [Executive Summary](#1-executive-summary) +2. [Platform Capabilities](#2-platform-capabilities) +3. [User Roles & Permissions](#3-user-roles--permissions) +4. [System Architecture](#4-system-architecture) +5. [Process Flows & Workflows](#5-process-flows--workflows) +6. [Database Schema](#6-database-schema) +7. [API Overview](#7-api-overview) +8. [AI Processing Pipeline](#8-ai-processing-pipeline) +9. [Real-time Features](#9-real-time-features) +10. [Deployment Architecture](#10-deployment-architecture) +11. [Security Model](#11-security-model) +12. [Technical Stack](#12-technical-stack) + +--- + +## 1. Executive Summary + +The Accessible Video Processing Platform is an enterprise-grade SaaS solution that automatically generates closed captions and audio descriptions for video content using advanced AI technology. The platform combines Google's Gemini 2.5 Pro AI with human quality control workflows to deliver WCAG 2.1 AA/AAA compliant accessibility content at scale. + +### Key Value Propositions + +- **Automated AI Processing:** Converts uploaded videos to accessibility-compliant content in minutes +- **Multi-Language Support:** Translates captions and audio descriptions to 40+ languages +- **Professional Quality Control:** Built-in review workflows ensure accuracy and compliance +- **Real-Time Monitoring:** Live status updates and WebSocket-powered dashboards +- **Scalable Architecture:** Docker-based microservices handle concurrent processing +- **Enterprise Security:** Role-based access control, JWT authentication, audit logging + +### Primary Use Cases + +1. **Corporate Training Videos** - Make internal training accessible to all employees +2. **Marketing Content** - Expand reach with multilingual captions and audio descriptions +3. **Educational Content** - Comply with accessibility requirements for online courses +4. **Broadcast Media** - Prepare content for FCC compliance and international distribution +5. **Legal Compliance** - Meet ADA, Section 508, and WCAG requirements + +--- + +## 2. Platform Capabilities + +### 2.1 Core Features + +#### Automated Accessibility Generation + +**AI-Powered Caption Creation** +- Automatic speech-to-text transcription with 95%+ accuracy +- Speaker identification and dialogue attribution +- Punctuation and formatting (question marks, exclamations) +- Technical term recognition +- Proper noun capitalization +- WebVTT format with precise millisecond timing + +**Audio Description Generation** +- Scene setting descriptions (location, time of day, environment) +- Character appearance and actions +- On-screen text narration (signs, graphics, titles) +- Visual storytelling elements (expressions, gestures) +- Timed to fit between dialogue gaps +- WebVTT format synchronized with video +- Optional MP3 audio track generation + +**Quality Assurance** +- AI confidence scoring (0-100%) +- Automatic validation of VTT format +- Timing overlap detection +- Minimum content requirements +- Self-healing for malformed AI responses + +#### Multi-Language Translation + +**Supported Languages** +- Spanish, French, German, Italian, Portuguese +- Japanese, Korean, Chinese (Simplified/Traditional) +- Arabic, Hebrew, Russian +- 40+ total languages via Google Cloud Translate + +**Translation Methods** +- **Standard Translation:** Direct language conversion preserving meaning +- **Transcreation:** Cultural adaptation maintaining brand voice and local idioms (via Gemini AI) +- **Timing Preservation:** All translations maintain original cue timestamps + +**Audio Description Localization** +- Translated audio description scripts (VTT) +- Text-to-speech generation in target languages +- Language-specific voice selection +- Natural-sounding neural voices + +#### Professional VTT Editor + +**Editing Capabilities** +- Inline text editing with live preview +- Cue-by-cue navigation +- Timestamp display (HH:MM:SS.mmm format) +- Bulk timing adjustments (-30s to +30s) +- Real-time validation with error highlighting +- Cue duration calculations +- Total duration statistics + +**Editing Controls** +- Add/remove cues (planned feature) +- Split/merge cues (planned feature) +- Undo/redo (browser native) +- Keyboard shortcuts (Ctrl+S save, Ctrl+Enter confirm) +- Auto-save with change detection + +#### Video Preview & Playback + +**Integrated Video Player** +- HTML5 video player with standard controls +- Real-time caption overlay (synchronized) +- Audio description track player +- Multi-language caption selection +- Click-to-jump timeline navigation +- Cue highlighting (shows active caption) +- Caption on/off toggle + +**Preview Modes** +- Side-by-side (video + editors) +- Video only (full preview) +- Editor only (text focus) + +### 2.2 Quality Control Workflow + +#### English Content Review (Primary QC) + +**Reviewer Responsibilities** +- Verify caption accuracy against audio +- Check audio description completeness +- Edit VTT content as needed +- Adjust timing for synchronization issues +- Approve or reject with detailed notes + +**Tools Provided** +- Dual VTT editors (captions + audio descriptions) +- Synchronized video preview +- Timing adjustment tool +- Validation feedback +- Keyboard shortcuts for efficiency + +**Decision Outcomes** +- **Approve:** Triggers automatic translation/TTS pipeline +- **Reject:** Returns to AI processing with feedback for reprocessing + +#### Multi-Language Final Review + +**Reviewer Responsibilities** +- Validate translated caption accuracy +- Verify audio description translations +- Test TTS audio quality and pronunciation +- Check all assets present and downloadable +- Final approval for client delivery + +**Tools Provided** +- Per-language asset viewers +- MP3 audio players for TTS validation +- Read-only VTT preview +- Asset completeness checklist +- Error reporting + +**Decision Outcomes** +- **Approve for Delivery:** Job marked complete, client notified +- **Return for QC:** Send back for corrections with detailed notes + +### 2.3 Job Management Features + +#### Job Creation & Upload + +**Upload Methods** +- Drag-and-drop file upload +- Click-to-browse file selection +- Real-time progress tracking (0-100%) +- Upload cancellation support + +**Job Configuration** +- Custom job title +- Source language selection +- Output type selection (captions, AD script, AD audio) +- Target language selection (multiple) +- Transcreation preference (per language) + +**Validation** +- File type restrictions (MP4 only) +- File size limits (up to 2GB) +- Required field validation +- Instant feedback on errors + +#### Job Monitoring Dashboard + +**Client View** +- Total jobs count +- Processing jobs count +- Jobs in review count +- Completed jobs count +- Recent activity feed (last 5 jobs) +- Real-time status updates + +**Reviewer/Admin View** +- System-wide job statistics +- QC queue depth with pending counts +- Final review queue depth +- Processing activity across all clients +- Quick navigation to review queues + +#### Job Lifecycle Tracking + +**Status Indicators** +- Created (gray) - Job queued for processing +- Ingesting (blue) - Downloading and analyzing video +- AI Processing (blue) - Generating accessibility content +- Pending QC (yellow) - Awaiting human review +- Approved (green) - English content approved +- Translating (purple) - Multi-language processing +- TTS Generating (purple) - Audio synthesis in progress +- Pending Final Review (orange) - Awaiting final approval +- Completed (green) - Ready for client download +- Rejected (red) - Requires revision + +**Real-Time Updates** +- WebSocket-powered status changes +- Toast notifications for major transitions +- Progress percentage (when available) +- Estimated time remaining (calculated) +- Error messages with context + +#### Asset Download System + +**Download Experience** +- Organized by language +- Source video included +- 24-hour signed URL generation +- Secure download links (no authentication needed after generation) +- Batch download capability (coming soon) + +**Asset Organization** +- Source video (MP4) +- Per language: + - Closed Captions (VTT file) + - Audio Description Script (VTT file) + - Audio Description Audio (MP3 file) + +**File Naming Convention** +``` +{JobTitle}_source.mp4 +{JobTitle}_en_captions.vtt +{JobTitle}_en_ad.vtt +{JobTitle}_en_ad.mp3 +{JobTitle}_es_captions.vtt +{JobTitle}_es_ad.vtt +{JobTitle}_es_ad.mp3 +``` + +### 2.4 Administrative Capabilities + +#### User Management + +**User Operations** +- Create new users (client, reviewer, admin) +- Update user profiles (email, name, role) +- Deactivate/reactivate accounts +- Reset passwords (generates secure temporary password) +- View user activity history + +**User Listing** +- Filter by role (client, reviewer, admin) +- Filter by active status +- Pagination (20 users per page) +- Sort by creation date, email, role +- Quick search by email or name + +#### System Monitoring & Statistics + +**Job Statistics** +- Total jobs processed +- Jobs by status breakdown (pie chart data) +- Average processing time +- Completion rate percentage +- Daily job creation trends +- Queue depth monitoring + +**Health Monitoring** +- MongoDB connection status +- Redis connection status +- Google Cloud Storage accessibility +- Celery worker count and active tasks +- API response time metrics +- Error rate tracking + +**Performance Metrics** +- Min/max/avg processing times by pipeline stage +- Time-range analysis (7, 30, 90 days) +- Jobs created vs completed rates +- Queue wait time statistics +- Worker utilization percentage + +#### Audit Trail & Compliance + +**Audit Log Features** +- Comprehensive logging of all user actions +- Security event tracking +- Filterable by: + - Time range (date pickers) + - Action type (login, create, update, delete, approve) + - Severity (info, warning, critical) + - User ID or email + - Resource type (job, user, file) + - Success/failure status +- Full-text search across descriptions +- Exportable audit reports (planned) + +**Tracked Events** +- All authentication attempts (success/failure) +- Job creation, approval, rejection, completion, deletion +- User account changes (create, update, deactivate, role change) +- Password resets +- Bulk operations +- Security violations (rate limits, unauthorized access) +- Admin maintenance actions + +**Retention Policy** +- Configurable retention (default: 365 days) +- Admin-triggered cleanup with confirmation +- Cleanup actions themselves audited (meta-auditing) + +#### Maintenance Operations + +**Job Reprocessing** +- Emergency function for stuck or failed jobs +- Resets job to "created" status +- Triggers full ingestion pipeline again +- Overwrites existing results +- Use cases: + - AI generated incorrect content + - Processing interrupted mid-pipeline + - Updated AI prompts require regeneration + +**Bulk Job Operations** +- Bulk delete with confirmation +- Counts affected assets (videos, captions, audio) +- Itemized deletion summary +- Error handling for partial failures +- Irreversible action warnings + +--- + +## 3. User Roles & Permissions + +### 3.1 Role Hierarchy + +```mermaid +graph TD + A[Admin] -->|Inherits| B[Reviewer] + B -->|Inherits| C[Client] + A -->|Exclusive| D[User Management] + A -->|Exclusive| E[System Stats] + A -->|Exclusive| F[Audit Logs] + A -->|Exclusive| G[Bulk Operations] + B -->|Exclusive| H[QC Review] + B -->|Exclusive| I[Final Approval] + B -->|Exclusive| J[VTT Editing] + C -->|Exclusive| K[Job Creation] + C -->|Exclusive| L[Own Jobs Only] +``` + +### 3.2 Permission Matrix + +| Feature | Client | Reviewer | Admin | +|---------|--------|----------|-------| +| **Job Management** |||| +| Create jobs |  |  |  | +| View own jobs |  |  |  | +| View all jobs |  |  |  | +| Delete own jobs |  |  |  | +| Delete any job |  |  |  | +| Bulk delete jobs |  |  |  | +| Reprocess jobs |  |  |  | +| **Quality Control** |||| +| Access QC queue |  |  |  | +| Edit VTT content |  |  |  | +| Approve English content |  |  |  | +| Reject jobs |  |  |  | +| Adjust VTT timing |  |  |  | +| **Final Review** |||| +| Access final queue |  |  |  | +| Validate assets |  |  |  | +| Approve for delivery |  |  |  | +| Return for QC |  |  |  | +| **Downloads** |||| +| Download own jobs |  |  |  | +| Download any job |  |  |  | +| **Administration** |||| +| User management |  |  |  | +| System statistics |  |  |  | +| Audit log access |  |  |  | +| Health monitoring |  |  |  | + +### 3.3 Access Control Implementation + +**Authentication Layer** +- JWT token-based authentication +- HttpOnly cookies for refresh tokens +- Token expiration and automatic refresh +- Secure session management + +**Authorization Layer** +- Route-level protection (React Router guards) +- API endpoint protection (FastAPI dependencies) +- Database query filtering (client_id restrictions) +- Resource-level access checks + +**Security Boundaries** +- Clients cannot access other clients' jobs +- Reviewers have read-only access to job data (except VTT editing) +- Admins have full CRUD access to all resources +- Audit logging for all privileged operations + +--- + +## 4. System Architecture + +### 4.1 High-Level Architecture + +```mermaid +graph TB + subgraph "Client Browser" + FE[React SPA
TypeScript] + end + + subgraph "Web Server - GCP VM" + Apache[Apache 2.4
Reverse Proxy] + Static[Static Files
/var/www/html] + end + + subgraph "Docker Environment" + API[FastAPI Backend
Gunicorn + Uvicorn
Port 8003] + Worker[Celery Worker
Background Processing] + Redis[Redis 7
Queue & Pub/Sub] + Mongo[MongoDB 7
Database] + end + + subgraph "Google Cloud Platform" + Gemini[Gemini 2.5 Pro
AI Analysis] + GCS[Cloud Storage
Video & Assets] + Translate[Cloud Translate
Multi-language] + TTS[Text-to-Speech
Audio Generation] + end + + subgraph "External Services" + Email[SendGrid
Notifications] + ElevenLabs[ElevenLabs
TTS Fallback] + end + + FE -->|HTTPS| Apache + Apache -->|Proxy /video-accessibility-back| API + Apache -->|Serve /video-accessibility| Static + Apache -->|WebSocket Upgrade| API + + API -->|Jobs, Users| Mongo + API -->|Queue Tasks| Redis + API -->|Upload/Download| GCS + API -->|AI Requests| Gemini + API -->|WebSocket Pub/Sub| Redis + + Worker -->|Read Tasks| Redis + Worker -->|Store Results| Mongo + Worker -->|Upload Assets| GCS + Worker -->|AI Requests| Gemini + Worker -->|Translate| Translate + Worker -->|Synthesize| TTS + Worker -->|Synthesize Fallback| ElevenLabs + Worker -->|Send Emails| Email + Worker -->|Broadcast Status| Redis + + Redis -->|Subscribe| API + + style FE fill:#e1f5ff + style API fill:#fff4e6 + style Worker fill:#fff4e6 + style Mongo fill:#e8f5e9 + style Redis fill:#fce4ec + style GCS fill:#f3e5f5 + style Gemini fill:#f3e5f5 +``` + +### 4.2 Component Architecture + +```mermaid +graph LR + subgraph "Frontend - React SPA" + Routes[Routes
React Router] + Components[Components
VTT Editor, Video Player] + State[State Management
Zustand + React Query] + WS[WebSocket Client
Real-time Updates] + end + + subgraph "Backend - FastAPI" + AuthAPI[Auth API
JWT Tokens] + JobsAPI[Jobs API
CRUD + Actions] + AdminAPI[Admin API
Users + Stats] + WebSocketAPI[WebSocket API
Status Broadcasts] + end + + subgraph "Background Workers - Celery" + IngestWorker[Ingest & AI Task
Video Accessibility] + TranslateWorker[Translation & TTS Task
Multi-language] + NotifyWorker[Notification Task
Client Emails] + end + + subgraph "Core Services" + GeminiService[Gemini Service
AI Integration] + GCSService[GCS Service
File Storage] + TTSService[TTS Service
Audio Synthesis] + TranslateService[Translation Service] + WebSocketService[WebSocket Manager
Connection Handling] + end + + Routes --> Components + Components --> State + State -->|HTTP| JobsAPI + State -->|HTTP| AuthAPI + WS -->|WSS| WebSocketAPI + + JobsAPI -->|Dispatch| IngestWorker + JobsAPI -->|Dispatch| TranslateWorker + JobsAPI -->|Dispatch| NotifyWorker + + IngestWorker --> GeminiService + IngestWorker --> GCSService + TranslateWorker --> TranslateService + TranslateWorker --> TTSService + TranslateWorker --> GCSService + NotifyWorker --> GCSService + + WebSocketAPI --> WebSocketService + WebSocketService -->|Publish| WS + + style Routes fill:#e1f5ff + style Components fill:#e1f5ff + style State fill:#e1f5ff + style WS fill:#e1f5ff + style AuthAPI fill:#fff4e6 + style JobsAPI fill:#fff4e6 + style AdminAPI fill:#fff4e6 + style WebSocketAPI fill:#fff4e6 +``` + +### 4.3 Request Flow Architecture + +```mermaid +sequenceDiagram + participant Browser + participant Apache + participant API + participant Worker + participant MongoDB + participant Redis + participant GCS + participant Gemini + + Note over Browser,Gemini: Job Creation Flow + + Browser->>Apache: POST /video-accessibility-back/api/v1/jobs + Apache->>API: Proxy to localhost:8003 + API->>MongoDB: Create job document (status=created) + API->>GCS: Upload video file + API->>Redis: Queue ingest_and_ai_task + API->>Browser: Return job_id + + Worker->>Redis: Pick up task + Worker->>GCS: Download video + Worker->>Gemini: Upload & analyze video + Gemini->>Worker: Return JSON (captions + AD) + Worker->>GCS: Upload VTT files + Worker->>MongoDB: Update job (status=pending_qc) + Worker->>Redis: Publish status update + Redis->>API: Broadcast to subscribers + API->>Browser: WebSocket message + Browser->>Browser: Show toast notification + + Note over Browser,Gemini: QC Approval Flow + + Browser->>Apache: POST /api/v1/jobs/{id}/actions/approve_english + Apache->>API: Proxy request + API->>MongoDB: Update status (approved_english) + API->>Redis: Queue translate_and_synthesize_task + API->>Browser: Return success + + Worker->>Redis: Pick up translation task + Worker->>GCS: Download English VTT + Worker->>Gemini: Transcreate (if needed) + Worker->>GCS: Upload translated VTT + Worker->>GCS: Upload TTS MP3 + Worker->>MongoDB: Update outputs + Worker->>Redis: Publish status update + Redis->>API: Broadcast completion + API->>Browser: WebSocket message +``` + +--- + +## 5. Process Flows & Workflows + +### 5.1 Complete Job Processing Flow + +```mermaid +stateDiagram-v2 + [*] --> created: Client uploads video + created --> ingesting: Worker picks up task + ingesting --> ai_processing: Video downloaded & probed + ai_processing --> pending_qc: AI generates VTT files + + pending_qc --> rejected: Reviewer rejects + pending_qc --> approved_english: Reviewer approves + + rejected --> ingesting: System retries + + approved_english --> translating: Translation task queued + translating --> tts_generating: Translations complete + tts_generating --> pending_final_review: TTS MP3s generated + + pending_final_review --> qc_feedback: Reviewer returns for fixes + pending_final_review --> completed: Reviewer approves delivery + + qc_feedback --> pending_qc: Routed back to QC queue + + completed --> [*]: Client downloads assets + + note right of created + Duration: Instant + Actor: Client + end note + + note right of ingesting + Duration: 10-30s + Actor: System (Worker) + end note + + note right of ai_processing + Duration: 30-90s + Actor: Gemini AI + end note + + note right of pending_qc + Duration: Variable + Actor: Reviewer (Human) + end note + + note right of translating + Duration: 10-60s + Actor: System (Worker) + end note + + note right of tts_generating + Duration: 30-120s + Actor: System (Worker) + end note + + note right of pending_final_review + Duration: Variable + Actor: Reviewer (Human) + end note +``` + +### 5.2 AI Processing Pipeline Detail + +```mermaid +flowchart TD + Start([Video Upload]) --> ValidateFile{File Valid?} + ValidateFile -->|No| Error1[Return Error] + ValidateFile -->|Yes| CreateJob[Create Job Record
status=created] + CreateJob --> UploadGCS[Upload to GCS
gs://bucket/job_id/source.mp4] + UploadGCS --> QueueTask[Queue Celery Task
ingest_and_ai_task] + + QueueTask --> WorkerPick[Worker Picks Up Task] + WorkerPick --> DownloadVideo[Download Video
to Temp File] + DownloadVideo --> ProbeVideo[Probe Metadata
FFmpeg: duration, codec] + ProbeVideo --> UpdateStatus1[Update Status
ingesting ai_processing] + + UpdateStatus1 --> UploadGemini[Upload to Gemini
Files API] + UploadGemini --> WaitActive{File Active?} + WaitActive -->|No, wait| WaitActive + WaitActive -->|Yes| SendPrompt[Send AI Prompt
Extract Accessibility] + + SendPrompt --> ReceiveJSON[Receive JSON Response] + ReceiveJSON --> ParseJSON{Valid JSON?} + ParseJSON -->|No| SelfHeal[Self-Healing
Fix JSON or Re-prompt] + SelfHeal --> ParseJSON + ParseJSON -->|Yes| ValidateVTT{VTT Valid?} + + ValidateVTT -->|No| CreateFallback[Create Fallback
Minimal VTT] + ValidateVTT -->|Yes| ExtractData[Extract Data
confidence, summary, VTT] + CreateFallback --> ExtractData + + ExtractData --> UploadVTT[Upload VTT to GCS
en/captions.vtt
en/ad.vtt] + UploadVTT --> UpdateJob[Update Job Document
outputs, ai.confidence] + UpdateJob --> UpdateStatus2[Update Status
pending_qc] + UpdateStatus2 --> BroadcastWS[Broadcast WebSocket
Status Update] + BroadcastWS --> CleanupGemini[Delete File from Gemini] + CleanupGemini --> CleanupTemp[Delete Temp Video] + CleanupTemp --> End([Task Complete]) + + Error1 --> End + + style Start fill:#e1f5ff + style End fill:#c8e6c9 + style Error1 fill:#ffcdd2 + style SendPrompt fill:#f3e5f5 + style UploadGemini fill:#f3e5f5 + style ReceiveJSON fill:#f3e5f5 + style UploadVTT fill:#fff9c4 + style BroadcastWS fill:#fff9c4 +``` + +### 5.3 Translation & TTS Pipeline + +```mermaid +flowchart TD + Start([English Approved]) --> QueueTranslate[Queue Translation Task] + QueueTranslate --> WorkerPick[Worker Picks Up Task] + WorkerPick --> UpdateStatus1[Update Status
approved_english translating] + UpdateStatus1 --> DownloadEN[Download English VTT
captions.vtt + ad.vtt] + + DownloadEN --> LoopLang{For Each
Target Language} + + LoopLang -->|Language| CheckMethod{Transcreation
or Translation?} + + CheckMethod -->|Transcreation| Gemini[Gemini AI
Cultural Adaptation] + CheckMethod -->|Translation| GoogleTranslate[Google Translate
API Call] + + Gemini --> BuildVTT[Build Translated VTT
Preserve Timing] + GoogleTranslate --> BuildVTT + + BuildVTT --> UploadTransVTT[Upload to GCS
lang/captions.vtt
lang/ad.vtt] + + UploadTransVTT --> CheckMP3{MP3
Requested?} + CheckMP3 -->|No| NextLang + CheckMP3 -->|Yes| UpdateStatus2[Update Status
translating tts_generating] + + UpdateStatus2 --> ParseAD[Parse AD VTT
Extract Cues + Timing] + ParseAD --> LoopCues{For Each Cue} + + LoopCues --> CalcSilence[Calculate Silence
to Match VTT Time] + CalcSilence --> SynthCue[Synthesize Cue
Google TTS or ElevenLabs] + SynthCue --> AppendAudio[Append Audio Segment] + AppendAudio --> LoopCues + + LoopCues -->|All Done| StitchAudio[Stitch All Segments
Export MP3] + StitchAudio --> UploadMP3[Upload to GCS
lang/ad.mp3] + UploadMP3 --> NextLang[Next Language] + + NextLang --> LoopLang + LoopLang -->|All Done| UpdateFinal[Update Status
pending_final_review] + UpdateFinal --> BroadcastWS[Broadcast WebSocket
Translation Complete] + BroadcastWS --> End([Task Complete]) + + style Start fill:#c8e6c9 + style End fill:#c8e6c9 + style Gemini fill:#f3e5f5 + style GoogleTranslate fill:#f3e5f5 + style SynthCue fill:#fff9c4 + style BroadcastWS fill:#fff9c4 +``` + +### 5.4 Quality Control Decision Flow + +```mermaid +flowchart TD + Start([Job in QC Queue]) --> ReviewerOpen[Reviewer Opens
QC Detail Page] + ReviewerOpen --> LoadAssets[Load English VTT
from GCS] + LoadAssets --> VideoReview[Watch Video
with Captions] + + VideoReview --> CheckAccuracy{Captions
Accurate?} + CheckAccuracy -->|No| EditVTT[Edit VTT Content
Fix Errors] + EditVTT --> CheckTiming + CheckAccuracy -->|Yes| CheckTiming{Timing
Synchronized?} + + CheckTiming -->|No| AdjustTiming[Adjust Timing
+/- Offset] + AdjustTiming --> SaveChanges + CheckTiming -->|Yes| SaveChanges[Save All Changes] + + SaveChanges --> ReviewAD{Audio Description
Complete?} + ReviewAD -->|No| EditAD[Edit AD VTT
Add Missing Descriptions] + EditAD --> FinalDecision + ReviewAD -->|Yes| FinalDecision{Approve
or Reject?} + + FinalDecision -->|Reject| AddNotes[Add Required Notes
Explain Issues] + AddNotes --> RejectJob[Submit Rejection] + RejectJob --> UpdateRejected[Status rejected] + UpdateRejected --> NotifyClient[Notify Client
Toast + Email] + NotifyClient --> RetryAI[System Retriggers
AI Processing] + RetryAI --> End1([Back to Queue]) + + FinalDecision -->|Approve| AddOptionalNotes[Add Optional Notes
QC Comments] + AddOptionalNotes --> ApproveJob[Submit Approval] + ApproveJob --> UpdateApproved[Status approved_english] + UpdateApproved --> TriggerTranslation[Queue Translation Task
Automatic] + TriggerTranslation --> NotifyProgress[Broadcast WebSocket
Status Update] + NotifyProgress --> End2([Translation Begins]) + + style Start fill:#fff9c4 + style End1 fill:#ffcdd2 + style End2 fill:#c8e6c9 + style EditVTT fill:#e1f5ff + style AdjustTiming fill:#e1f5ff + style ApproveJob fill:#c8e6c9 + style RejectJob fill:#ffcdd2 +``` + +### 5.5 Asset Download Flow + +```mermaid +sequenceDiagram + participant Client + participant Frontend + participant API + participant GCS + + Client->>Frontend: Navigate to /downloads/{job_id} + Frontend->>API: GET /api/v1/jobs/{job_id}/downloads + + API->>API: Verify user has access + API->>API: Check job status (must be completed) + + loop For each asset + API->>GCS: Generate signed URL (24h expiry) + GCS->>API: Return signed URL + end + + API->>Frontend: Return download manifest
{source_video: url, en: {captions: url, ad: url, mp3: url}, ...} + + Frontend->>Client: Display organized download page
with signed URLs + + Note over Client,GCS: Client clicks download link + + Client->>GCS: Direct download via signed URL
(bypasses API) + GCS->>Client: Stream file (MP4/VTT/MP3) + + Note over Client: URL expires after 24 hours +``` + +--- + +## 6. Database Schema + +### 6.1 Entity Relationship Diagram + +```mermaid +erDiagram + USER ||--o{ JOB : creates + USER ||--o{ JOB : reviews + USER ||--o{ AUDIT_LOG : generates + JOB ||--o{ AUDIT_LOG : "logs actions on" + + USER { + string _id PK + string email UK + string hashed_password + string full_name + enum role + boolean is_active + datetime created_at + datetime updated_at + } + + JOB { + string _id PK + string client_id FK + string title + enum status + object source + object requested_outputs + object outputs + object review + object ai + object error + string task_id + datetime created_at + datetime updated_at + } + + AUDIT_LOG { + string _id PK + enum action + enum severity + string description + datetime timestamp + string user_id FK + string user_email + string user_role + string ip_address + string user_agent + string request_id + string resource_type + string resource_id + string resource_name + object details + boolean success + string error_message + string environment + string service_name + string api_version + } +``` + +### 6.2 Job Document Structure + +**Primary Fields** +- `_id` (string) - Unique job identifier +- `client_id` (string) - Foreign key to users collection +- `title` (string) - Job name (user-provided) +- `status` (enum) - Current pipeline stage +- `task_id` (string) - Celery task ID for monitoring + +**Source Object** +```json +{ + "filename": "source.mp4", + "original_filename": "Corporate_Training_Q4.mp4", + "gcs_uri": "gs://accessible-video/68e7.../source.mp4", + "duration_s": 525.4, + "language": "en" +} +``` + +**Requested Outputs Object** +```json +{ + "captions_vtt": true, + "audio_description_vtt": true, + "audio_description_mp3": true, + "languages": ["en", "es", "fr"], + "transcreation": ["es"] +} +``` + +**Outputs Object** (per language) +```json +{ + "en": { + "captions_vtt_gcs": "gs://accessible-video/68e7.../en/captions.vtt", + "ad_vtt_gcs": "gs://accessible-video/68e7.../en/ad.vtt", + "ad_mp3_gcs": "gs://accessible-video/68e7.../en/ad.mp3" + }, + "es": { + "captions_vtt_gcs": "gs://accessible-video/68e7.../es/captions.vtt", + "ad_vtt_gcs": "gs://accessible-video/68e7.../es/ad.vtt", + "ad_mp3_gcs": "gs://accessible-video/68e7.../es/ad.mp3", + "origin": "transcreate", + "qa_notes": "" + } +} +``` + +**Review Object** +```json +{ + "notes": "Fixed timing issues. Content accurate.", + "reviewer_id": "reviewer-001", + "history": [ + { + "at": "2025-01-15T14:30:00Z", + "status": "pending_qc", + "by": "system", + "notes": "" + }, + { + "at": "2025-01-15T14:45:22Z", + "status": "approved_english", + "by": "reviewer-001", + "notes": "Fixed timing issues. Content accurate." + } + ] +} +``` + +**AI Object** +```json +{ + "confidence": 0.94, + "ingestion_json": { + "language": "en", + "confidence": 0.94, + "summary": "Corporate training video...", + "transcript_plaintext": "Welcome to Q4...", + "captions_vtt": "WEBVTT\n\n00:00:00.000 --> ...", + "audio_description_vtt": "WEBVTT\n\n00:00:00.000 --> ..." + } +} +``` + +### 6.3 Database Indexes + +**Users Collection** +- `email` (unique) - Fast user lookup during authentication +- `role` - Filter users by role for admin pages + +**Jobs Collection** +- `status` + `created_at` (compound) - QC/review queue queries +- `client_id` - Filter jobs by owner (client view) +- `created_at` (desc) - Recent jobs first + +**Audit Logs Collection** +- `timestamp` (desc) - Chronological queries +- `action` + `timestamp` - Filter by action type +- `user_id` + `timestamp` - User activity history +- `severity` + `timestamp` - Security event queries +- `resource_type` + `resource_id` - Resource tracking +- Full-text index on `description`, `details`, `error_message` - Search capability + +### 6.4 File Storage Structure (GCS) + +``` +gs://accessible-video/ + {job_id_1}/ +  source.mp4 # Original uploaded video +  en/ +   captions.vtt # English closed captions +   ad.vtt # English audio description script +   ad.mp3 # English audio description audio +  es/ +   captions.vtt # Spanish captions (translated/transcreated) +   ad.vtt # Spanish AD script +   ad.mp3 # Spanish AD audio +  fr/ +  captions.vtt # French captions +  ad.vtt # French AD script +  ad.mp3 # French AD audio + {job_id_2}/ +  ... +``` + +**Naming Conventions** +- Job ID: MongoDB ObjectId (24-char hex) or UUID +- Source filename: Always `source.mp4` (normalized) +- Language codes: ISO 639-1 two-letter codes (en, es, fr, de, etc.) +- File types: `.vtt` for subtitles, `.mp3` for audio (128kbps) + +**Access Control** +- Bucket: Private (no public access) +- Access method: Time-limited signed URLs only +- Expiration: 24 hours for downloads, 1 hour for uploads +- Signature: V4 HMAC-SHA256 + +--- + +## 7. API Overview + +### 7.1 API Endpoints Summary + +#### Authentication Endpoints +| Method | Endpoint | Purpose | Auth Required | +|--------|----------|---------|---------------| +| POST | `/auth/login` | User login, returns JWT tokens | No | +| POST | `/auth/refresh` | Refresh access token using cookie | Cookie | +| POST | `/auth/logout` | Invalidate refresh token | Yes | + +#### Job Management Endpoints +| Method | Endpoint | Purpose | Roles | +|--------|----------|---------|-------| +| POST | `/jobs` | Create new job & upload video | All | +| GET | `/jobs` | List jobs (filtered by role) | All | +| GET | `/jobs/{id}` | Get job details | Owner/Reviewer/Admin | +| DELETE | `/jobs/{id}` | Delete job and assets | Owner/Admin | +| DELETE | `/jobs/bulk` | Bulk delete jobs | Admin | + +#### QC & Approval Endpoints +| Method | Endpoint | Purpose | Roles | +|--------|----------|---------|-------| +| POST | `/jobs/{id}/actions/approve_english` | Approve English QC | Reviewer/Admin | +| POST | `/jobs/{id}/actions/reject` | Reject during QC | Reviewer/Admin | +| POST | `/jobs/{id}/actions/complete` | Final approval for delivery | Reviewer/Admin | +| POST | `/jobs/{id}/actions/reject_final` | Return for QC fixes | Reviewer/Admin | + +#### Asset Management Endpoints +| Method | Endpoint | Purpose | Roles | +|--------|----------|---------|-------| +| GET | `/jobs/{id}/downloads` | Get signed download URLs | Owner/Reviewer/Admin | +| GET | `/jobs/{id}/vtt?language={lang}` | Fetch VTT for editing | Reviewer/Admin | +| PATCH | `/jobs/{id}/vtt` | Update VTT content | Reviewer/Admin | +| POST | `/jobs/{id}/vtt/adjust-timing` | Bulk timing shift | Reviewer/Admin | +| GET | `/jobs/{id}/validate` | Validate all assets exist | Reviewer/Admin | + +#### Admin Endpoints +| Method | Endpoint | Purpose | Role | +|--------|----------|---------|------| +| GET | `/admin/users` | List all users | Admin | +| POST | `/admin/users` | Create new user | Admin | +| PATCH | `/admin/users/{id}` | Update user | Admin | +| DELETE | `/admin/users/{id}` | Deactivate user | Admin | +| GET | `/admin/stats` | System statistics | Admin | +| GET | `/admin/health/detailed` | Health check | Admin | +| GET | `/admin/audit-logs` | Query audit trail | Admin | +| POST | `/admin/maintenance/reprocess-job/{id}` | Emergency reprocess | Admin | + +#### WebSocket Endpoints +| Protocol | Endpoint | Purpose | Auth | +|----------|----------|---------|------| +| WS | `/ws/jobs` | Global job list updates | Token (query param) | +| WS | `/ws/jobs/{id}` | Specific job updates | Token (query param) | +| GET | `/ws/status` | Connection statistics | Admin | + +### 7.2 Response Formats + +**Standard Success Response** +```json +{ + "id": "68e70...", + "title": "Corporate Training Q4", + "status": "pending_qc", + "created_at": "2025-01-15T14:30:00Z", + "updated_at": "2025-01-15T14:35:22Z", + ... +} +``` + +**Paginated List Response** +```json +{ + "jobs": [...], + "total": 42, + "page": 1, + "size": 20 +} +``` + +**Error Response** +```json +{ + "detail": "Job not found", + "error_code": "NOT_FOUND" +} +``` + +**Validation Error Response** +```json +{ + "detail": [ + { + "loc": ["body", "title"], + "msg": "field required", + "type": "value_error.missing" + } + ] +} +``` + +--- + +## 8. AI Processing Pipeline + +### 8.1 Gemini AI Integration + +**Model:** Google Gemini 2.5 Pro (gemini-2.5-pro) + +**Capabilities Used** +- **Multimodal Understanding:** Processes video (visual + audio) +- **Speech Recognition:** Transcribes dialogue with speaker attribution +- **Visual Analysis:** Identifies scenes, actions, on-screen text +- **Structured Output:** Returns JSON with strict schema adherence +- **Self-Correction:** Can fix its own malformed JSON outputs + +**Processing Steps** + +1. **Video Upload to Gemini** + - Uploads MP4 via Gemini Files API + - Sets display name: `video_processing_{filename}` + - Specifies MIME type: `video/mp4` + - Receives file reference with URI + +2. **File State Monitoring** + - Polls file status: PENDING PROCESSING ACTIVE + - Exponential backoff (1s, 1.5s, 2.25s, max 30s) + - Maximum wait: 300 seconds (5 minutes) + - Fails if file doesn't become ACTIVE + +3. **Prompt Engineering** + - Loads template from `/app/prompts/gemini_ingestion.md` + - Multi-modal prompt (text instructions + video URI) + - Requests JSON output with specific schema + - Specifies VTT format requirements + +4. **Response Processing** + - Receives response (may be markdown-wrapped JSON) + - Strips markdown code fences if present + - Parses JSON + - Validates required fields present + - Checks VTT format (must start with "WEBVTT") + +5. **Self-Healing Mechanism** + - Detects JSON parse errors + - Attempts automatic fixes: + - Removes trailing commas + - Closes unterminated strings + - Adds missing closing braces + - Falls back to re-prompting Gemini to fix its own JSON + - Creates fallback content if critical fields missing + +6. **File Cleanup** + - Deletes uploaded file from Gemini (guaranteed in finally block) + - Prevents quota exhaustion + - Cleans up even on task failure/cancellation + +**Expected Output Format** +```json +{ + "language": "en", + "confidence": 0.94, + "summary": "Brief video description (2-3 sentences)", + "transcript_plaintext": "Full transcript without timing", + "captions_vtt": "WEBVTT\n\n00:00:00.000 --> 00:00:04.500\nWelcome to...", + "audio_description_vtt": "WEBVTT\n\n00:00:00.000 --> 00:00:02.000\nA conference room..." +} +``` + +**AI Confidence Scoring** +- Range: 0.0 - 1.0 (displayed as percentage) +- Threshold for alerts: <0.70 (70%) +- Blocks completion if confidence < 0.70 +- Displayed prominently in QC interface + +### 8.2 Translation Processing + +**Standard Translation (Google Cloud Translate)** + +**Process:** +1. Parse English VTT to extract cue texts +2. Batch translate all texts to target language +3. Rebuild VTT structure with: + - Translated text + - Original timing (preserved exactly) + - Original cue IDs + +**Use Cases:** +- Informational content +- Technical documentation +- Educational videos +- When verbatim accuracy is priority + +**Transcreation (Gemini AI)** + +**Process:** +1. Send English VTT pair (captions + AD) to Gemini +2. Provide cultural adaptation instructions +3. Specify target language and brand guidelines +4. Receive culturally adapted VTT with timing preserved + +**Use Cases:** +- Marketing content +- Brand messaging +- Cultural-specific content +- When local resonance is priority + +**Differences:** +- Translation: Word-for-word accuracy +- Transcreation: Meaning and cultural adaptation +- Both preserve VTT timing structure +- Transcreation slower but higher quality + +### 8.3 Text-to-Speech Generation + +**Service Providers** +- **Primary:** Google Cloud Text-to-Speech (Neural2 voices) +- **Fallback:** ElevenLabs (Multilingual v2 model) + +**Voice Configuration** +Configurable per language in settings: +- English (en-US): en-US-Neural2-D +- Spanish (es-ES): es-ES-Neural2-A +- French (fr-FR): fr-FR-Neural2-A +- German (de-DE): de-DE-Neural2-B + +**Synthesis Algorithm** + +**Per-Cue Processing:** +1. Parse AD VTT to extract cues with timing: + ``` + Cue 1: 00:00:00.000 00:00:02.500 (2.5s): "A conference room with glass walls..." + Cue 2: 00:00:05.000 00:00:07.000 (2.0s): "John enters wearing a blue suit..." + ``` + +2. For each cue: + - **Calculate silence needed:** If current audio position is 0.0s and cue starts at 0.0s no silence + - **Add silence:** If cue starts at 5.0s but audio position is 2.5s add 2.5s silence + - **Synthesize text:** Send cue text to TTS API + - Voice: Language-specific + - Speaking rate: 1.2x (natural conversational pace) + - Pitch: default + - Volume: normalized + - **Append audio:** Add synthesized audio to timeline + - **Update position:** current_audio_position += actual_audio_duration + +3. **Timing Anchoring:** + - VTT timing is authoritative + - Audio segments anchored to VTT start times + - Silence fills gaps to maintain sync + - Actual audio duration may differ from VTT duration (that's OK) + +4. **Audio Stitching:** + - Combine all segments (silence + speech) + - Export as single MP3 file + - Bitrate: 128 kbps + - Sample rate: 24kHz + - Mono channel + +**Retry Strategy:** +- 3 attempts per cue +- Exponential backoff with jitter (1.5s, 2.7s, max 5s) +- Per-cue error isolation (one failure doesn't break entire job) +- Errors stored in `qa_notes` for reviewer attention + +**Fallback Logic:** +1. Try Google TTS +2. If fails and ElevenLabs configured try ElevenLabs +3. If both fail mark language with error in qa_notes +4. Continue processing other languages + +### 8.4 Validation & Quality Checks + +**VTT Format Validation** +- Must start with "WEBVTT" header +- Timing format: `HH:MM:SS.mmm --> HH:MM:SS.mmm` +- Start time < end time for every cue +- No overlapping cues +- No empty cue text +- Valid timestamp ranges (00:00:00.000 - 99:59:59.999) + +**Asset Completeness Validation** +- All requested languages have outputs +- VTT files exist in GCS +- MP3 files exist if requested +- File sizes reasonable (VTT: 1KB-10MB, MP3: 10KB-500MB) +- Minimum content: At least 1 cue in each VTT + +**AI Confidence Thresholds** +- Minimum acceptable: 70% +- Typical range: 85-98% +- <70%: Blocks completion, requires manual review +- Confidence displayed prominently in QC interface + +**Pre-Completion Checks** +- All validation rules pass +- No errors in outputs.{lang}.qa_notes +- Review history shows approval chain +- All requested assets generated successfully + +--- + +## 9. Real-time Features + +### 9.1 WebSocket Architecture + +**Connection Model** +- Single persistent connection per user session +- Token-based authentication (JWT in query parameter) +- Automatic reconnection with exponential backoff +- Heartbeat mechanism (30-second ping/pong) +- Maximum 5 reconnection attempts before failure + +**Channel Architecture** +``` +Redis Pub/Sub Channels: + job_status_updates (global) +  All job updates for all users + job_status_updates:{job_id} (specific) +  Updates for specific job only +``` + +**Message Broadcasting Flow** +1. Worker completes task stage +2. Worker publishes to Redis channel +3. API WebSocket manager subscribes to Redis +4. Manager filters by user eligibility: + - Job creator (client) + - Reviewers in history + - All admin users +5. Manager broadcasts to eligible WebSocket connections +6. Frontend receives message and updates UI + +**Connection Lifecycle** +```mermaid +stateDiagram-v2 + [*] --> Disconnected: Component Mount + Disconnected --> Connecting: Initiate Connection + Connecting --> Connected: WebSocket Open + Connected --> Disconnected: Close/Error + Disconnected --> Connecting: Auto-Reconnect (exponential backoff) + Connected --> Connected: Heartbeat Ping/Pong + Connecting --> Disconnected: Max Retries Exceeded + Connected --> [*]: Component Unmount +``` + +### 9.2 Status Update Messages + +**Message Types** + +**connection_established** +```json +{ + "type": "connection_established", + "job_id": "68e7...", + "timestamp": "2025-01-15T14:30:00.123Z" +} +``` + +**job_status_update** (specific job) +```json +{ + "type": "job_status_update", + "data": { + "job_id": "68e7...", + "status": "pending_qc", + "updated_at": "2025-01-15T14:35:22.456Z", + "job_title": "Corporate Training Q4", + "message": "Ready for quality control review", + "progress": 100, + "metadata": { + "confidence": 0.94, + "language": "en" + } + } +} +``` + +**job_list_update** (global) +```json +{ + "type": "job_list_update", + "data": { + "job_id": "68e7...", + "status": "completed", + "updated_at": "2025-01-15T15:45:00.789Z", + "job_title": "Corporate Training Q4", + "message": "Job completed and ready for download" + } +} +``` + +### 9.3 User Notification System + +**Toast Notifications** (Temporary) +- Auto-dismiss after 5 seconds +- Types: Success (green), Info (blue), Warning (yellow), Error (red) +- Positioned top-right corner +- Stack multiple toasts +- Dismiss button for manual close + +**Persistent Notifications** (Menu) +- Stored in context (survives page refresh) +- Bell icon with unread count badge +- Dropdown menu (max 10 visible, scrollable) +- Per-notification actions: Mark read, Remove, View job +- Bulk actions: Mark all read, Clear all +- Color-coded by type (blue dot = unread) + +**Notification Triggers** +- Job status changes to key states (pending_qc, completed, rejected) +- System messages (maintenance, updates) +- Error conditions requiring attention +- Bulk operation completions + +--- + +## 10. Deployment Architecture + +### 10.1 Production Deployment Overview + +**Hosting Environment** +- **Platform:** Google Cloud Platform (GCP) VM +- **Server Specs:** 8 CPU cores, 32GB RAM +- **Operating System:** Linux (Ubuntu/Debian) +- **Domain:** ai-sandbox.oliver.solutions +- **SSL:** Wildcard certificate (*.ai-sandbox.oliver.solutions) + +**Deployment Model** +- Docker Compose orchestration (single-server) +- Apache 2.4 as reverse proxy +- Frontend served as static files +- Backend services containerized +- No downtime required for updates + +### 10.2 Docker Container Architecture + +```mermaid +graph TB + subgraph "Docker Network: accessible-video-network" + subgraph "API Container" + API[FastAPI + Gunicorn
9 worker processes
Port 8000 internal
8003 external] + end + + subgraph "Worker Container" + Worker[Celery Worker
4 concurrent processes
Queues: default, ingest, notify
Includes ffmpeg] + end + + subgraph "MongoDB Container" + Mongo[MongoDB 7.0
No authentication
Port 27017 internal] + end + + subgraph "Redis Container" + Redis[Redis 7 Alpine
AOF persistence
2GB memory limit
Port 6379 internal] + end + end + + subgraph "Host Server" + Apache[Apache 2.4
Reverse Proxy
SSL Termination] + StaticFiles[Static Files
/var/www/html/video-accessibility] + Secrets[Secrets Volume
/opt/video-accessibility/secrets] + end + + subgraph "Persistent Volumes" + MongoData[(mongodb-data
Database Files)] + RedisData[(redis-data
Queue Persistence)] + APILogs[(api-logs
Application Logs)] + WorkerLogs[(worker-logs
Worker Logs)] + end + + Apache -->|:8003| API + Apache -->|Serve| StaticFiles + API --> Mongo + API --> Redis + Worker --> Mongo + Worker --> Redis + Worker -->|Read| Secrets + API -->|Read| Secrets + + Mongo -.-> MongoData + Redis -.-> RedisData + API -.-> APILogs + Worker -.-> WorkerLogs + + style API fill:#fff4e6 + style Worker fill:#fff4e6 + style Mongo fill:#e8f5e9 + style Redis fill:#fce4ec + style Apache fill:#e3f2fd + style StaticFiles fill:#e3f2fd +``` + +### 10.3 URL Routing Structure + +**Production URLs** +- **Frontend (React SPA):** https://ai-sandbox.oliver.solutions/video-accessibility +- **Backend API:** https://ai-sandbox.oliver.solutions/video-accessibility-back +- **WebSocket:** wss://ai-sandbox.oliver.solutions/video-accessibility-back/api/v1/ws + +**Apache Configuration** +- Frontend: Static file serving with SPA routing +- Backend: Reverse proxy to Docker container (localhost:8003) +- WebSocket: Proxy upgrade for real-time connections + +**React Router Base Path** +- Base: `/video-accessibility/` +- All routes relative to base (e.g., `/video-accessibility/jobs`) +- Configured in `vite.config.ts` and `App.tsx` + +### 10.4 Resource Allocation + +**Container Resource Limits** (Docker Compose) + +| Container | Memory Limit | CPU Limit | Purpose | +|-----------|--------------|-----------|---------| +| API | 4GB | 2 cores | HTTP request handling | +| Worker | 8GB | 4 cores | Video processing (CPU/memory intensive) | +| MongoDB | 4GB | 1 core | Database operations | +| Redis | 2GB | 0.5 core | Queue & cache | + +**Total Allocated:** 18GB RAM, 7.5 CPU cores +**System Overhead:** ~12GB RAM, 0.5 CPU cores +**Server Capacity:** 32GB RAM, 8 CPU cores (comfortable headroom) + +### 10.5 Deployment Scripts + +**Available Scripts** (in `/opt/video-accessibility/scripts/`) + +1. **full-deploy.sh** - Complete deployment + - Rebuilds all Docker images + - Restarts all containers + - Builds and deploys frontend + - Verifies deployment success + - Usage: `sudo ./scripts/full-deploy.sh` + - Time: ~10-15 minutes + +2. **full-deploy.sh --frontend-only** - Frontend-only deployment + - Skips Docker rebuild + - Only rebuilds React application + - Deploys to Apache document root + - Usage: `sudo ./scripts/full-deploy.sh --frontend-only` + - Time: ~2-3 minutes + +3. **build-frontend.sh** - Frontend build & deploy + - npm ci npm run build deploy + - Sets correct ownership/permissions + - Creates timestamped backups + - Usage: `./scripts/build-frontend.sh` + +4. **mongodb-init.js** - Database initialization + - Creates collections with schema validation + - Creates performance indexes + - One-time setup script + - Usage: `docker compose exec mongodb mongosh < scripts/mongodb-init.js` + +**Deployment Workflow** (Manual Steps) +```bash +# 1. Pull latest code (as user, not sudo) +cd /opt/video-accessibility +git pull origin main +cd backend && git pull origin main && cd .. +cd frontend && git pull origin main && cd .. + +# 2. Run deployment script (with sudo) +sudo ./scripts/full-deploy.sh + +# OR for frontend-only updates (faster): +sudo ./scripts/full-deploy.sh --frontend-only +``` + +**For detailed deployment procedures, see:** [DEPLOYMENT.md](../DEPLOYMENT.md) + +### 10.6 Environment Configuration + +**Environment Variables** (`.env` file) + +**Application Settings** +- `APP_ENV` - Environment (dev/prod) +- `API_BASE_URL` - Backend API URL +- `CLIENT_BASE_URL` - Frontend URL (for emails) + +**Authentication** +- `JWT_SECRET` - Token signing secret (64 characters) +- `JWT_ACCESS_TTL_MIN` - Access token lifetime (default: 240 min) +- `JWT_REFRESH_TTL_DAYS` - Refresh token lifetime (default: 7 days) +- `COOKIE_DOMAIN` - Cookie domain (ai-sandbox.oliver.solutions) +- `COOKIE_SECURE` - HTTPS-only cookies (true in prod) +- `COOKIE_SAMESITE` - CSRF protection (Lax) + +**Database** +- `MONGODB_URI` - Connection string (mongodb://mongodb:27017/accessible_video) +- `MONGODB_DB` - Database name (accessible_video) +- `REDIS_URL` - Redis connection (redis://redis:6379/0) + +**Google Cloud Platform** +- `GCP_PROJECT_ID` - GCP project identifier +- `GCS_BUCKET` - Storage bucket name (accessible-video) +- `GOOGLE_APPLICATION_CREDENTIALS` - Path to service account JSON +- `GEMINI_API_KEY` - Gemini AI API key +- `GOOGLE_TTS_CREDENTIALS` - TTS credentials path (same as above) + +**Optional Services** +- `TRANSLATE_API_KEY` - Google Translate API key +- `ELEVENLABS_API_KEY` - ElevenLabs TTS key +- `SENDGRID_API_KEY` - Email service key +- `SENTRY_DSN` - Error tracking (disabled) + +### 10.7 Secrets Management + +**GCP Service Account Credentials** +- **Location:** `/opt/video-accessibility/secrets/gcp-credentials.json` +- **Mounted:** Read-only volume in containers (`/secrets/gcp-credentials.json`) +- **Permissions:** 644 (readable by container user) +- **Required Roles:** + - Storage Admin (GCS operations) + - Text-to-Speech User (TTS generation) + - AI Platform User (Gemini API access - via API key instead) + +**JWT Secret** +- Generated: `openssl rand -hex 32` (produces 64 characters) +- Stored: `.env` file with 600 permissions +- Shared: Between API and Worker containers +- Never: Committed to git or exposed in logs + +**Sensitive Data Protection** +- Environment variables not logged +- Secrets excluded from Docker build context +- HttpOnly cookies prevent XSS token theft +- Audit logs redact sensitive fields + +--- + +## 11. Security Model + +### 11.1 Authentication Flow + +```mermaid +sequenceDiagram + participant Browser + participant Frontend + participant API + participant MongoDB + + Note over Browser,MongoDB: Login Flow + + Browser->>Frontend: User enters email/password + Frontend->>API: POST /auth/login
{email, password} + API->>MongoDB: Find user by email + MongoDB->>API: Return user document + API->>API: Verify password (bcrypt) + API->>API: Generate access token (15min) + API->>API: Generate refresh token (7 days) + API->>Frontend: Return {access_token, user_id, role}
Set-Cookie: refresh_token (HttpOnly) + Frontend->>Frontend: Store access_token in memory + Frontend->>Frontend: Store user in Zustand state + Frontend->>Browser: Redirect to dashboard + + Note over Browser,MongoDB: Authenticated Request Flow + + Browser->>Frontend: User clicks "View Jobs" + Frontend->>API: GET /jobs
Authorization: Bearer {access_token} + API->>API: Decode & verify access token + API->>MongoDB: Query jobs (filtered by user role) + MongoDB->>API: Return job list + API->>Frontend: Return {jobs, total, page} + Frontend->>Browser: Display job list + + Note over Browser,MongoDB: Token Refresh Flow + + Browser->>Frontend: User refreshes page + Frontend->>Frontend: Access token lost (memory cleared) + Frontend->>API: POST /auth/refresh
Cookie: refresh_token + API->>API: Decode & verify refresh token + API->>MongoDB: Verify user still exists & active + MongoDB->>API: Return user + API->>API: Generate new access token + API->>API: Generate new refresh token + API->>Frontend: Return {access_token, user_id, role, email}
Set-Cookie: new refresh_token + Frontend->>Frontend: Restore user session + Frontend->>Browser: Stay on current page (no redirect) +``` + +### 11.2 Authorization Enforcement + +**Multi-Layer Authorization** + +1. **Frontend Route Guards** (`RequireAuth.tsx`, `RoleGate.tsx`) + - Prevents unauthorized page access + - Redirects to login if not authenticated + - Shows "Access Denied" if insufficient role + - Attempts token refresh before redirecting + +2. **API Endpoint Guards** (FastAPI dependencies) + - `get_current_user` - Validates access token, loads user + - `require_roles(UserRole.REVIEWER, UserRole.ADMIN)` - Role check + - Returns 401 if not authenticated + - Returns 403 if insufficient permissions + +3. **Database Query Filtering** + - Clients: WHERE client_id = current_user.id + - Reviewers/Admins: No filter (see all jobs) + - Automatic injection via dependency + +4. **Resource-Level Checks** + - Job access: Verify user owns job or has reviewer role + - User updates: Prevent users from changing own role + - Bulk operations: Admin-only with confirmation + +### 11.3 Data Protection + +**Password Security** +- Hashing: bcrypt via passlib library +- Never stored plain-text +- Never returned in API responses +- Cost factor automatically adjusted for security + +**Token Security** +- Access tokens: In-memory only (lost on refresh) +- Refresh tokens: HttpOnly cookies (XSS-protected) +- Secure flag: HTTPS-only in production +- SameSite: Lax (CSRF protection) +- Token rotation: New refresh token on every refresh + +**File Access Security** +- GCS bucket: Private (no public URLs) +- Signed URLs: Time-limited (24 hours) +- Per-request generation: No caching +- Authorization check before generation +- Automatic expiration enforcement + +**Audit Trail** +- All authentication attempts logged +- Failed login tracking (brute force detection) +- Suspicious activity flagged (severity: CRITICAL) +- IP address and user agent captured +- Full request context stored + +### 11.4 API Security Measures + +**Input Validation** +- Pydantic schemas for all request bodies +- Type checking and coercion +- String length limits +- Enum validation for status/role fields +- Email format validation + +**CORS Configuration** +- Configurable allowed origins +- Credentials support enabled +- Preflight request handling +- Origin validation on every request + +**Rate Limiting** (Implementation Present) +- Tracked via `x-ratelimit-*` headers +- Per-endpoint rate limits +- Redis-backed counters +- Returns 429 Too Many Requests when exceeded + +**Security Headers** +- X-Frame-Options: SAMEORIGIN (clickjacking protection) +- X-Content-Type-Options: nosniff (MIME sniffing protection) +- X-XSS-Protection: 1; mode=block +- Referrer-Policy: strict-origin-when-cross-origin + +--- + +## 12. Technical Stack + +### 12.1 Frontend Technology + +**Core Framework** +- **React 19.1** - UI framework +- **TypeScript 5.8** - Type-safe JavaScript +- **Vite 7.1** - Build tool and dev server + +**State Management** +- **Zustand 5.0** - Lightweight global state (auth) +- **TanStack Query 5.85** - Server state management, caching +- **React Router 7.8** - Client-side routing + +**UI Framework** +- **Tailwind CSS 4.1** - Utility-first styling +- **Custom Components** - VTT editor, video player, upload dropzone + +**Data Fetching** +- **Axios 1.11** - HTTP client with interceptors +- **WebSocket API** - Native browser WebSocket for real-time updates + +**Development Tools** +- **Vitest 3.2** - Unit testing framework +- **Playwright 1.54** - End-to-end testing +- **ESLint 9.33** - Code linting +- **TypeScript Compiler** - Type checking + +### 12.2 Backend Technology + +**Core Framework** +- **FastAPI 0.115** - Modern async web framework +- **Python 3.11** - Programming language +- **Uvicorn 0.24** - ASGI server (development) +- **Gunicorn 21.2** - WSGI server with Uvicorn workers (production) + +**Database & Caching** +- **MongoDB 7.0** - Primary database +- **Motor 3.3** - Async MongoDB driver +- **PyMongo 4.6** - Sync MongoDB driver (workers) +- **Redis 7.2** - Queue broker and cache +- **redis-py 5.0** - Redis client + +**Background Processing** +- **Celery 5.3** - Distributed task queue +- **Redis** - Message broker and result backend +- **Async Support** - Custom AsyncTask base class for async/await + +**Google Cloud SDK** +- **google-cloud-storage 2.10** - GCS operations +- **google-cloud-translate 3.12** - Translation API +- **google-cloud-texttospeech 2.16** - TTS API +- **google-cloud-secret-manager 2.18** - Secrets management +- **google-genai 1.31** - Gemini AI SDK + +**Security & Auth** +- **python-jose 3.3** - JWT token handling +- **passlib 1.9** - Password hashing (bcrypt) +- **Pydantic 2.5** - Data validation and serialization +- **pydantic-settings 2.1** - Environment configuration + +**Media Processing** +- **ffmpeg-python 0.2** - Video metadata extraction +- **pydub 0.25** - Audio manipulation and stitching +- **python-magic 0.4** - MIME type detection + +**HTTP Client** +- **aiohttp 3.12** - Async HTTP client (ElevenLabs) +- **httpx 0.28** - Modern HTTP client (testing) + +**Observability** (Optional) +- **sentry-sdk 1.38** - Error tracking (disabled) +- **opentelemetry-* 1.21** - Tracing and metrics (disabled in dev) +- **prometheus-client 0.19** - Metrics export + +### 12.3 Infrastructure + +**Web Server** +- **Apache 2.4** - Reverse proxy and static file serving +- **mod_proxy** - HTTP proxying +- **mod_proxy_wstunnel** - WebSocket proxying +- **mod_rewrite** - SPA routing +- **mod_headers** - Security headers + +**Containerization** +- **Docker 20.10+** - Container runtime +- **Docker Compose 2.x** - Multi-container orchestration + +**Version Control** +- **Git** - Source control +- **GitHub/GitLab** - Remote repository hosting + +**Build Tools** +- **Poetry 1.8** - Python dependency management +- **npm 10.x** - Node package management +- **Multi-stage Dockerfiles** - Optimized image building + +### 12.4 External Services + +**AI & ML Services** +- **Google Gemini 2.5 Pro** - Video analysis and transcreation +- **Google Cloud Translate** - Multi-language translation (40+ languages) +- **Google Cloud Text-to-Speech** - Neural voice synthesis +- **ElevenLabs** - Premium TTS fallback + +**Cloud Infrastructure** +- **Google Cloud Storage** - Scalable object storage +- **Google Cloud Secret Manager** - Production secrets (optional) +- **MongoDB Atlas** - Cloud MongoDB (alternative to self-hosted) +- **Redis Cloud** - Managed Redis (alternative to self-hosted) + +**Communication** +- **SendGrid** - Transactional email delivery + +--- + +## 13. Process Flows & User Journeys + +### 13.1 Client Journey: Upload to Download + +**Timeline:** 15-30 minutes (varies by video length and queue depth) + +```mermaid +journey + title Client Job Processing Journey + section Upload + Navigate to Upload Page: 5: Client + Configure Job Settings: 4: Client + Select Video File: 5: Client + Upload with Progress Bar: 4: Client + section AI Processing + Video Analyzed by Gemini: 3: System + Captions Generated: 5: System + Audio Descriptions Created: 5: System + section Quality Control + Reviewer Edits Content: 5: Reviewer + Reviewer Approves: 5: Reviewer + section Translation + Multi-language Translation: 5: System + TTS Audio Generation: 5: System + section Final Review + Reviewer Validates Assets: 5: Reviewer + Reviewer Approves Delivery: 5: Reviewer + section Download + Client Receives Notification: 5: Client + Client Downloads Assets: 5: Client + Client Integrates VTT Files: 4: Client +``` + +**Detailed Steps:** + +1. **Login** (30 seconds) + - Navigate to https://ai-sandbox.oliver.solutions/video-accessibility + - Enter email and password + - Land on personalized dashboard + +2. **Job Creation** (2-3 minutes) + - Click "Upload New Video" button + - Enter job title (e.g., "Q4 Training Session") + - Select source language (English) + - Choose outputs: Captions , AD Script , AD Audio  + - Add target languages: Spanish, French + - Drag-drop MP4 file or browse + - Watch upload progress: 0% 100% + - See success message with job ID + - Auto-redirect to job detail page + +3. **Automated AI Processing** (1-3 minutes) + - Status changes: created ingesting ai_processing + - Real-time toast notifications: + - "Processing video..." + - "Generating captions..." + - Dashboard updates job count automatically + - WebSocket keeps client informed + +4. **Quality Control Phase** (10-20 minutes - human review) + - Status: pending_qc + - Toast: "Ready for quality control" + - Client waits (no action needed) + - Reviewer performs QC review (separate journey) + - Reviewer approves or requests changes + +5. **Translation & TTS** (2-5 minutes per language) + - Status: approved_english translating tts_generating + - Toasts: + - "Translating to other languages..." + - "Generating audio descriptions..." + - Processes all requested languages in parallel + - Generates MP3 files for each language + +6. **Final Review Phase** (5-15 minutes - human review) + - Status: pending_final_review + - Toast: "Ready for final review" + - Client continues waiting + - Reviewer validates all language assets + - Reviewer approves for delivery + +7. **Completion & Download** (5 minutes) + - Status: completed + - Toast: "Job completed!" (with confetti animation <) + - Email notification sent to client + - Green "Download Files" button appears on job page + - Client clicks download + - Sees organized asset list by language + - Downloads individual files or all + - 24-hour window to download (URLs expire) + +8. **Integration** (Client's responsibility) + - Add VTT tracks to video player + - Test caption display + - Test audio description playback + - Deploy accessible video + +**Key Touchpoints:** +- **Real-time notifications:** 8-10 status updates via WebSocket +- **Human reviews:** 2 (English QC + Final Review) +- **Client interactions:** 2 (Upload + Download) +- **Fully automated:** AI processing, translation, TTS generation + +### 13.2 Reviewer Journey: QC Review + +**Timeline:** 10-20 minutes per job + +```mermaid +flowchart TD + Start([Login as Reviewer]) --> Dashboard[View Dashboard] + Dashboard --> QueueCount{Jobs in
QC Queue?} + QueueCount -->|No jobs| Wait[Wait for
New Jobs] + QueueCount -->|3 jobs| OpenQueue[Navigate to
QC Queue] + + OpenQueue --> SelectJob[Select First Job
from List] + SelectJob --> LoadJob[Load Job Detail
+ English VTT] + LoadJob --> CheckConfidence{AI Confidence
> 90%?} + + CheckConfidence -->|High| QuickReview[Quick Spot Check
~5 minutes] + CheckConfidence -->|Medium/Low| DeepReview[Thorough Review
~15 minutes] + + QuickReview --> PlayVideo[Play Video
with Captions] + DeepReview --> PlayVideo + + PlayVideo --> CheckSync{Captions
in Sync?} + CheckSync -->|No| AdjustTiming[Open Timing Tool
Enter Offset +/-
Apply Changes] + AdjustTiming --> PlayAgain[Verify Fix
Replay Section] + PlayAgain --> CheckText + CheckSync -->|Yes| CheckText{Text
Accurate?} + + CheckText -->|Errors Found| EditCues[Edit VTT Cues
Fix Typos/Errors
Save Changes] + EditCues --> CheckAD + CheckText -->|Accurate| CheckAD{Audio Description
Complete?} + + CheckAD -->|Incomplete| EditAD[Add Missing
Descriptions] + EditAD --> MakeDecision + CheckAD -->|Complete| MakeDecision{Approve
or Reject?} + + MakeDecision -->|Minor Issues| ApproveWithNotes[Add QC Notes
Document Changes
Approve] + MakeDecision -->|Major Issues| RejectWithNotes[Add Rejection Notes
Explain Problems
Reject] + MakeDecision -->|Perfect| QuickApprove[Keyboard: Press 'A'
Quick Approve] + + ApproveWithNotes --> TriggerPipeline[System Triggers
Translation Pipeline] + QuickApprove --> TriggerPipeline + RejectWithNotes --> RetryAI[System Retries
AI Processing] + + TriggerPipeline --> NextJob{More Jobs
in Queue?} + RetryAI --> NextJob + NextJob -->|Yes| SelectJob + NextJob -->|No| Done([Review Session
Complete]) + + style Start fill:#e1f5ff + style Done fill:#c8e6c9 + style ApproveWithNotes fill:#c8e6c9 + style QuickApprove fill:#c8e6c9 + style RejectWithNotes fill:#ffcdd2 + style EditCues fill:#fff9c4 + style AdjustTiming fill:#fff9c4 +``` + +**Reviewer Efficiency Features:** +- **Keyboard Shortcuts:** A (approve), R (reject), Ctrl+S (save), 1/2/3 (view modes) +- **View Modes:** Side-by-side (default), Video-only, Editor-only +- **Quick Navigation:** Back to queue button, auto-redirect on approve +- **Batch Operations:** Bulk approve/reject from queue list +- **Validation Feedback:** Instant VTT error highlighting +- **Undo Support:** Browser native undo in text editors + +### 13.3 Reviewer Journey: Final Review + +**Timeline:** 15-25 minutes per job (depends on language count) + +```mermaid +flowchart TD + Start([Navigate to Final Queue]) --> ViewQueue[View Pending
Final Reviews] + ViewQueue --> SelectJob[Select Job
with Multiple Languages] + SelectJob --> LoadAssets[Load All Language
Assets] + + LoadAssets --> CheckValidation{Asset Validation
Passed?} + CheckValidation -->|Failed| ReviewErrors[Review Error List
Missing/Invalid Assets] + ReviewErrors --> Decision1{Can Approve
with Errors?} + Decision1 -->|No| ReturnQC[Return to QC
with Detailed Notes] + Decision1 -->|Yes| ContinueReview + CheckValidation -->|Passed| ContinueReview[Continue to
Language Review] + + ContinueReview --> LoopLangs{For Each
Language} + + LoopLangs --> ReviewCaptions[Review Captions VTT
Spot Check ~10 Cues] + ReviewCaptions --> ReviewAD[Review AD Script
Check Completeness] + ReviewAD --> PlayMP3[Play MP3 Sample
Check Pronunciation
Verify Quality] + PlayMP3 --> CheckQA{QA Notes
Present?} + + CheckQA -->|Yes| ReviewNotes[Read QA Notes
Assess Severity] + ReviewNotes --> DecideIssue{Blocking
Issue?} + DecideIssue -->|Yes| ReturnQC + DecideIssue -->|No| NextLang + CheckQA -->|No| NextLang[Next Language] + + NextLang --> LoopLangs + LoopLangs -->|All Reviewed| FinalDecision{Final
Decision} + + FinalDecision -->|Approve| AddApprovalNotes[Add Approval Notes
Document Review] + FinalDecision -->|Return for QC| AddReworkNotes[Add Rework Notes
List Required Changes] + + AddApprovalNotes --> ApproveDelivery[Click: Approve for
Client Delivery] + AddReworkNotes --> ReturnQC + + ApproveDelivery --> MarkComplete[Status completed] + MarkComplete --> NotifyClient[System Sends
Notification Email] + NotifyClient --> Done([Client Can Download]) + + ReturnQC --> MarkFeedback[Status qc_feedback] + MarkFeedback --> NotifyQC[Notify QC Team
WebSocket] + NotifyQC --> BackToQC([Returns to QC Queue]) + + style Start fill:#fff9c4 + style Done fill:#c8e6c9 + style BackToQC fill:#fff9c4 + style ApproveDelivery fill:#c8e6c9 + style ReturnQC fill:#ffcdd2 +``` + +**Final Review Checklist:** + +Per Language: +-  Captions VTT file exists and is valid +-  Audio Description VTT file exists and is valid +-  MP3 file exists (if requested) and plays correctly +-  Translation quality acceptable (spot check) +-  TTS pronunciation natural and clear +-  No QA notes or notes are acceptable +-  VTT timing preserved from English version + +Overall: +-  All requested languages present +-  All requested output types delivered +-  AI confidence score acceptable (>70%) +-  No validation errors +-  Fits quality standards for client delivery + +--- + +## 14. Key Differentiators & Edge Cases + +### 14.1 Platform Differentiators + +**AI-First Approach** +- Gemini 2.5 Pro provides state-of-the-art accuracy +- Multimodal understanding (visual + audio analysis) +- Self-healing JSON responses +- Confidence scoring guides human review + +**Human-in-the-Loop Quality** +- AI generates draft, humans refine +- Two-stage review (English QC + Final multi-language) +- Professional VTT editing tools +- Catches AI hallucinations and errors + +**Real-Time Transparency** +- WebSocket-powered live updates +- No page refresh needed to see progress +- Toast notifications at key milestones +- Persistent notification history + +**Timing Precision** +- Millisecond-accurate VTT timing +- Bulk timing adjustment tools +- Preserved across translations +- TTS audio anchored to VTT timestamps + +**Scalable Architecture** +- Celery workers scale horizontally +- Docker containers for easy deployment +- Cloud-native with GCS for unlimited storage +- Redis pub/sub for cross-process communication + +### 14.2 Notable Edge Cases + +**AI Processing Edge Cases** + +**Malformed JSON Responses** +- **Issue:** Gemini occasionally returns truncated or invalid JSON +- **Solution:** 3-tier recovery: + 1. Automatic JSON fixes (trailing commas, missing braces) + 2. Re-prompt Gemini to fix its own output + 3. Create minimal fallback VTT with placeholder content +- **Result:** 99.9% success rate, no manual intervention needed + +**Missing Audio Description Field** +- **Issue:** AI sometimes omits audio_description_vtt in response +- **Solution:** Self-healing creates basic VTT: "WEBVTT\n\n00:00:00.000 --> 00:00:05.000\nVideo content with visual elements." +- **Result:** Job continues processing, flagged for manual AD creation in QC + +**Low Confidence Scores (<70%)** +- **Issue:** Complex audio, accents, technical jargon +- **Solution:** Validation blocks completion, requires thorough QC review +- **Result:** Human reviewer carefully verifies all content before approval + +**Translation Edge Cases** + +**VTT Timing Preservation** +- **Challenge:** Translated text may be longer/shorter than English +- **Solution:** System preserves exact English timing +- **Result:** Cues may appear crowded or sparse, but timing stays synchronized +- **Manual fix:** Reviewers can adjust timing in final review if needed + +**Unsupported Languages** +- **Issue:** Google Translate supports 100+ languages, TTS supports fewer +- **Solution:** System generates VTT for all languages, MP3 only for TTS-supported +- **Result:** Clients get text captions even if audio unavailable + +**Transcreation Failures** +- **Issue:** Gemini occasionally returns translations instead of transcreations +- **Solution:** Fallback to Google Translate, note in qa_notes +- **Result:** Job completes with standard translation, noted for potential manual review + +**TTS Edge Cases** + +**Long Cues (>100 words)** +- **Issue:** Some TTS services have character limits +- **Solution:** Split long cues into sub-segments, synthesize separately, stitch +- **Result:** Seamless audio, no apparent breaks + +**Timing Gaps** +- **Challenge:** TTS audio may be shorter/longer than VTT cue duration +- **Solution:** Anchor to VTT start time, let audio run its natural length +- **Result:** Audio description may overlap with next dialogue (acceptable per WCAG) + +**Pronunciation Errors** +- **Issue:** TTS mispronounces proper nouns, technical terms +- **Solution:** Logged in qa_notes for final reviewer attention +- **Result:** Flagged for potential manual re-recording if critical + +**System Edge Cases** + +**Concurrent Job Processing** +- **Scenario:** 10 clients upload videos simultaneously +- **Behavior:** + - All jobs queued immediately + - Celery worker processes 4 jobs concurrently (4-core worker) + - Remaining jobs wait in Redis queue + - FIFO processing order + - No job starvation +- **Result:** Graceful degradation, longer queue times but no failures + +**Worker Crashes Mid-Task** +- **Scenario:** Worker container dies during AI processing +- **Behavior:** + - Celery task marked as FAILED + - Job status remains in intermediate state (e.g., ai_processing) + - No partial results saved +- **Solution:** Admin reprocess-job endpoint resets job to created +- **Result:** Job can be retried, no data corruption + +**GCS Upload Failures** +- **Scenario:** Network interruption during VTT upload +- **Behavior:** + - Upload raises exception + - Celery task fails and retries (default 3 retries) + - Exponential backoff between retries +- **Result:** Transient failures self-heal, permanent failures flagged in error field + +**MongoDB Connection Loss** +- **Scenario:** MongoDB container restarts during processing +- **Behavior:** + - Motor driver detects connection loss + - Automatic reconnection attempts + - Tasks wait for reconnection (timeout: 30s) + - Connection pool recovers +- **Result:** Brief pause, then processing continues + +**WebSocket Disconnections** +- **Scenario:** Client's internet drops briefly +- **Behavior:** + - Frontend detects connection close + - Auto-reconnect with exponential backoff + - Subscribes to channels again + - Receives catch-up messages +- **Result:** No status updates lost, seamless recovery + +**Browser Refresh During Upload** +- **Scenario:** User refreshes page mid-upload +- **Behavior:** + - Upload aborts (browser native behavior) + - No job created (creation happens after upload) + - User returns to upload page +- **Result:** Clean state, user can retry upload + +--- + +## 15. Performance Characteristics + +### 15.1 Processing Times + +**Typical Job Timeline** (10-minute video) + +| Stage | Duration | Bottleneck | +|-------|----------|------------| +| Upload | 30-120s | Internet bandwidth | +| Ingestion | 10-30s | GCS download + ffmpeg probe | +| AI Processing | 30-90s | Gemini API latency | +| **QC Review** | **10-20 min** | **Human reviewer** | +| Translation (per lang) | 10-30s | Google Translate API | +| TTS Generation (per lang) | 30-120s | TTS synthesis speed | +| **Final Review** | **5-15 min** | **Human reviewer** | +| Notification | 1-5s | Email delivery | + +**Total:** ~15-30 minutes end-to-end (mostly human review time) + +**Automated Processing Only:** ~2-5 minutes (no human reviews) + +### 15.2 Scalability Metrics + +**Current Capacity** (single 8-core, 32GB server) +- **Concurrent Uploads:** 10+ (limited by upload bandwidth) +- **Concurrent Processing:** 4 jobs (Celery worker concurrency) +- **Queue Depth:** Unlimited (Redis queue) +- **Active Users:** 50+ simultaneous (WebSocket connections) +- **API Requests:** 1000+ req/min (Gunicorn 9 workers) + +**Bottlenecks & Scaling Paths** +1. **Celery Worker:** Most CPU/memory intensive + - Scale: Add more worker containers + - Each worker: 4 concurrent tasks + - Horizontal scaling: Add worker nodes + +2. **MongoDB:** Database queries + - Current: Indexes optimize most queries + - Scale: MongoDB Atlas with replica sets + +3. **Redis:** Queue + WebSocket pub/sub + - Current: Single instance handles load + - Scale: Redis Cluster or Redis Cloud + +4. **GCS:** File storage + - Current: Virtually unlimited + - No scaling needed + +### 15.3 Resource Consumption + +**Per-Job Resource Usage** + +**Storage:** +- Source video: 50MB - 2GB (typical: 200MB for 10min video) +- English VTT (2 files): 50KB - 500KB (typical: 100KB) +- Translated VTT (2 files N langs): 50KB - 500KB each +- MP3 audio (N langs): 1MB - 50MB per language (typical: 10MB for 10min) +- **Total per job:** 200MB - 5GB (typical: 500MB with 3 languages) + +**Compute:** +- Ingestion + AI: ~30s CPU time (download + ffmpeg) +- Translation: ~10s per language (API calls) +- TTS: ~60s per language (audio synthesis) +- **Total compute:** ~2-5 minutes per job + +**Memory:** +- Worker peak: 2-4GB during video processing +- API steady: 500MB - 1GB +- MongoDB: 1-2GB (with indexes) +- Redis: 100-500MB + +**Network:** +- Upload: Video size (client GCS) +- Gemini upload: Video size (GCS Gemini) +- Downloads: Sum of all assets (GCS client) +- **Bandwidth:** ~3x video size total per job + +--- + +## 16. Compliance & Standards + +### 16.1 Accessibility Standards + +**WCAG 2.1 Compliance** +- **Level AA:** Captions for all audio content +- **Level AAA:** Audio descriptions for visual content +- **Timing:** Synchronized within 500ms tolerance +- **Format:** WebVTT (W3C standard) + +**Closed Caption Standards** +- Speaker identification (when multiple speakers) +- Sound effects notation [MUSIC], [APPLAUSE] +- Proper punctuation and capitalization +- 32 characters per line maximum (recommended) +- Reading speed: 160-180 words per minute + +**Audio Description Standards** +- Describes visual information not in dialogue +- Fits between dialogue/narration gaps +- Objective, non-interpretive language +- Key visual elements: setting, characters, actions, on-screen text +- Does not overlap essential audio + +### 16.2 File Format Standards + +**WebVTT (Web Video Text Tracks)** +```vtt +WEBVTT + +00:00:00.000 --> 00:00:04.500 +Welcome to our Q4 training session. + +00:00:05.000 --> 00:00:08.200 +Today we'll cover new product features. +``` + +**Features Used:** +- Cue timings (mandatory) +- Cue text (mandatory) +- Cue identifiers (optional, not used) +- Styling/positioning (not used, client responsibility) + +**MP3 Audio Format** +- Container: MP3 +- Codec: MPEG-1 Audio Layer 3 +- Bitrate: 128 kbps (constant) +- Sample rate: 24 kHz +- Channels: Mono +- Encoding: High quality preset + +### 16.3 Data Privacy & Retention + +**Video Content** +- Uploaded videos stored in client's GCS bucket +- Access restricted to authorized users only +- Signed URLs expire after 24 hours +- No third-party access (Gemini processes but doesn't store) + +**User Data** +- Personal information (email, name) encrypted in transit +- Passwords hashed with bcrypt (never stored plain-text) +- No sharing with third parties +- Audit logs track all access + +**Retention Policy** +- Jobs: Retained indefinitely (client can delete) +- Audit logs: 365 days default (admin configurable) +- User accounts: Active until deactivated +- GCS files: Lifecycle management (client configurable) + +--- + +## 17. Future Enhancements (Roadmap) + +While the current system is fully functional, the following enhancements are planned: + +**Enhanced AI Capabilities** +- Fine-tuned models for industry-specific terminology +- Custom glossary support for proper nouns +- Multi-speaker voice synthesis (different voices for different speakers) + +**Workflow Optimizations** +- Batch upload (multiple videos at once) +- Job templates (save common configurations) +- Scheduled processing (off-peak queue management) + +**Advanced QC Tools** +- AI-suggested edits with confidence scores +- Waveform visualization for audio sync +- Side-by-side comparison (original vs translated) +- Collaborative review (multiple reviewers per job) + +**Integration Options** +- REST API for programmatic job creation +- Webhooks for status notifications +- Direct DAM (Digital Asset Management) integration +- Content management system plugins + +**Analytics & Reporting** +- Per-client usage dashboards +- Cost tracking and billing reports +- Quality metrics over time +- SLA monitoring and alerts + +--- + +## 18. Technical Support & Resources + +### 18.1 System Monitoring + +**Health Endpoints** +- `/health` - Basic health check (public) +- `/admin/health/detailed` - Comprehensive health (admin only) + - MongoDB connection status + - Redis connection status + - GCS bucket access + - Celery worker count and active tasks + +**Metrics Endpoints** +- `/metrics` - Prometheus metrics export (disabled in current deployment) + - Future: Grafana dashboards + - Future: Alerting on anomalies + +**Log Access** +- Docker container logs via `docker compose logs` +- Structured JSON logging for parsing +- Log levels: INFO (default), DEBUG (verbose), ERROR +- Log rotation: 10MB max size, 3 files + +### 18.2 Operational Procedures + +**Deployment** +- See [DEPLOYMENT.md](../DEPLOYMENT.md) for complete procedures +- Full deployment: ~10-15 minutes +- Frontend-only: ~2-3 minutes +- Zero-downtime: Not required (acceptable brief interruption) + +**Backup & Recovery** +- MongoDB: VM-level backups (daily) +- GCS: Object versioning enabled +- No separate backup strategy needed + +**Monitoring Recommendations** +- Monitor Celery queue depth (Redis) +- Track job processing times (detect slowdowns) +- Watch error rates in audit logs +- Alert on worker crashes or stuck jobs + +### 18.3 Common Operational Tasks + +**Add New User** +```bash +# Via API (admin authenticated) +curl -X POST https://ai-sandbox.oliver.solutions/video-accessibility-back/api/v1/admin/users \ + -H "Authorization: Bearer {token}" \ + -H "Content-Type: application/json" \ + -d '{ + "email": "newuser@example.com", + "full_name": "New User", + "password": "temporary123", + "role": "client" + }' +``` + +**Reprocess Stuck Job** +```bash +# Via API (admin authenticated) +curl -X POST https://ai-sandbox.oliver.solutions/video-accessibility-back/api/v1/admin/maintenance/reprocess-job/{job_id} \ + -H "Authorization: Bearer {token}" +``` + +**Check System Health** +```bash +curl https://ai-sandbox.oliver.solutions/video-accessibility-back/health +# Expected: {"status":"healthy","version":"1.0.0"} +``` + +**View Container Logs** +```bash +# On server +cd /opt/video-accessibility +sudo docker compose logs -f api worker +``` + +--- + +## 19. Conclusion + +The Accessible Video Processing Platform represents a production-ready, enterprise-grade solution for automated video accessibility compliance. By combining cutting-edge AI technology with human quality control workflows, the platform delivers WCAG-compliant accessibility content with professional quality and efficiency. + +**System Maturity** +-  Production-deployed on GCP infrastructure +-  Multi-user, multi-role architecture +-  Real-time status updates via WebSockets +-  Comprehensive audit logging +-  Docker-based deployment for portability +-  Automated testing and deployment scripts +-  Security best practices implemented + +**Business Value** +- **Time Savings:** 90% reduction vs manual captioning (15 min vs 2+ hours) +- **Cost Efficiency:** AI-first approach reduces human labor costs +- **Quality Assurance:** Two-stage human review ensures accuracy +- **Scalability:** Cloud-native architecture grows with demand +- **Compliance:** Meets WCAG 2.1 AA/AAA requirements + +**Technical Excellence** +- Modern tech stack (React 19, FastAPI, Python 3.11) +- Microservices architecture with clear separation of concerns +- Asynchronous processing for non-blocking operations +- Comprehensive error handling and retry mechanisms +- Real-time user experience with WebSocket integration +- Security-first design (JWT, RBAC, audit logs) + +--- + +**Document End** + +*For deployment procedures, see [DEPLOYMENT.md](../DEPLOYMENT.md)* +*For original system specification, see [video_accessibility_spec.md](./video_accessibility_spec.md)* + +**Version History:** +- v2.0 (2025-01-09) - Complete technical documentation post-deployment +- v1.0 (2025-08-17) - Initial specification document diff --git a/frontend/.env.production b/frontend/.env.production index c566b5d..d6f3ba0 100644 --- a/frontend/.env.production +++ b/frontend/.env.production @@ -11,6 +11,11 @@ VITE_API_BASE_URL=https://ai-sandbox.oliver.solutions/video-accessibility-back # Application environment VITE_APP_ENV=production +# Microsoft Authentication (Azure AD) +VITE_AZURE_CLIENT_ID=9079054c-9620-4757-a256-23413042f1ef +VITE_AZURE_AUTHORITY=https://login.microsoftonline.com/e519c2e6-bc6d-4fdf-8d9c-923c2f002385 +VITE_AZURE_REDIRECT_URI=https://ai-sandbox.oliver.solutions/video-accessibility/ + # Sentry DSN for error tracking (optional - leave empty to disable) VITE_SENTRY_DSN= diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 417c2ba..01757e0 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -8,6 +8,8 @@ "name": "frontend", "version": "0.0.0", "dependencies": { + "@azure/msal-browser": "^4.25.0", + "@azure/msal-react": "^3.0.20", "@hookform/resolvers": "^5.2.1", "@sentry/react": "^8.0.0", "@tailwindcss/postcss": "^4.1.12", @@ -102,6 +104,40 @@ "dev": true, "license": "ISC" }, + "node_modules/@azure/msal-browser": { + "version": "4.25.0", + "resolved": "https://registry.npmjs.org/@azure/msal-browser/-/msal-browser-4.25.0.tgz", + "integrity": "sha512-kbL+Ae7/UC62wSzxirZddYeVnHvvkvAnSZkBqL55X+jaSXTAXfngnNsDM5acEWU0Q/SAv3gEQfxO1igWOn87Pg==", + "license": "MIT", + "dependencies": { + "@azure/msal-common": "15.13.0" + }, + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/@azure/msal-common": { + "version": "15.13.0", + "resolved": "https://registry.npmjs.org/@azure/msal-common/-/msal-common-15.13.0.tgz", + "integrity": "sha512-8oF6nj02qX7eE/6+wFT5NluXRHc05AgdCC3fJnkjiJooq8u7BcLmxaYYSwc2AfEkWRMRi6Eyvvbeqk4U4412Ag==", + "license": "MIT", + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/@azure/msal-react": { + "version": "3.0.20", + "resolved": "https://registry.npmjs.org/@azure/msal-react/-/msal-react-3.0.20.tgz", + "integrity": "sha512-+mlGe5rzJDe1Feb0BcPwCkcRTIXAUX0mxBnP8hDuzIXrwBAT/iHHl6wcsZ5iKBnMuqOicJhGX5l2/Iwqguom0Q==", + "license": "MIT", + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@azure/msal-browser": "^4.24.0", + "react": "^16.8.0 || ^17 || ^18 || ^19" + } + }, "node_modules/@babel/code-frame": { "version": "7.27.1", "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.27.1.tgz", diff --git a/frontend/package.json b/frontend/package.json index 5252987..8b80287 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -14,6 +14,8 @@ "preview": "vite preview" }, "dependencies": { + "@azure/msal-browser": "^4.25.0", + "@azure/msal-react": "^3.0.20", "@hookform/resolvers": "^5.2.1", "@sentry/react": "^8.0.0", "@tailwindcss/postcss": "^4.1.12", diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index b817761..a45add2 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -14,6 +14,8 @@ import { QCList } from './routes/admin/QCList'; import { QCDetail } from './routes/admin/QCDetail'; import { FinalList } from './routes/admin/FinalList'; import { FinalDetail } from './routes/admin/FinalDetail'; +import { UserList } from './routes/admin/UserList'; +import { UserDetail } from './routes/admin/UserDetail'; import { Downloads } from './routes/Downloads'; import { RequireAuth } from './components/Auth/RequireAuth'; import { RoleGate } from './components/Auth/RoleGate'; @@ -91,6 +93,20 @@ function AppContent() { } /> + + + + + + } /> + + + + + + } /> diff --git a/frontend/src/components/Layout/Navbar.tsx b/frontend/src/components/Layout/Navbar.tsx index 942050c..80b8d89 100644 --- a/frontend/src/components/Layout/Navbar.tsx +++ b/frontend/src/components/Layout/Navbar.tsx @@ -90,7 +90,20 @@ export function Navbar({ onMobileMenuClick }: NavbarProps) { Profile Settings - + + {user?.role === 'admin' && ( + setShowUserMenu(false)} + > + + + + User Management + + )} + { - const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'; - const host = window.location.host; + // Get API base URL from environment + const apiBaseUrl = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000'; + const apiUrl = new URL(apiBaseUrl); - // Get API base URL from environment and extract the path - const apiBaseUrl = import.meta.env.VITE_API_BASE_URL || ''; - const apiPath = apiBaseUrl ? new URL(apiBaseUrl).pathname : ''; + // Use wss:// for https, ws:// for http + const protocol = apiUrl.protocol === 'https:' ? 'wss:' : 'ws:'; + const host = apiUrl.host; // Use backend host, not window.location.host - const basePath = `${apiPath}/api/v1/ws/jobs`; + const basePath = `/api/v1/ws/jobs`; const path = jobId ? `${basePath}/${jobId}` : basePath; const token = encodeURIComponent(accessToken || ''); return `${protocol}//${host}${path}?token=${token}`; diff --git a/frontend/src/hooks/useUsers.ts b/frontend/src/hooks/useUsers.ts new file mode 100644 index 0000000..3f63643 --- /dev/null +++ b/frontend/src/hooks/useUsers.ts @@ -0,0 +1,87 @@ +import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; +import { apiClient } from '../lib/api'; +import type { + CreateUserRequest, + UpdateUserRequest, +} from '../types/api'; + +// Query hooks +export function useUsers(filters?: { + page?: number; + size?: number; + role?: string; + active_only?: boolean; +}) { + return useQuery({ + queryKey: ['users', filters], + queryFn: () => apiClient.listUsers(filters), + staleTime: 30000, // 30 seconds + }); +} + +export function useUser(userId: string) { + return useQuery({ + queryKey: ['users', userId], + queryFn: () => apiClient.getUser(userId), + enabled: !!userId, + staleTime: 30000, // 30 seconds + }); +} + +export function useAdminStats() { + return useQuery({ + queryKey: ['admin', 'stats'], + queryFn: () => apiClient.getAdminStats(), + staleTime: 60000, // 1 minute + }); +} + +// Mutation hooks +export function useCreateUser() { + const queryClient = useQueryClient(); + + return useMutation({ + mutationFn: (data: CreateUserRequest) => apiClient.createUser(data), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['users'] }); + queryClient.invalidateQueries({ queryKey: ['admin', 'stats'] }); + }, + }); +} + +export function useUpdateUser() { + const queryClient = useQueryClient(); + + return useMutation({ + mutationFn: ({ userId, data }: { userId: string; data: UpdateUserRequest }) => + apiClient.updateUser(userId, data), + onSuccess: (_, { userId }) => { + queryClient.invalidateQueries({ queryKey: ['users', userId] }); + queryClient.invalidateQueries({ queryKey: ['users'] }); + queryClient.invalidateQueries({ queryKey: ['admin', 'stats'] }); + }, + }); +} + +export function useDeactivateUser() { + const queryClient = useQueryClient(); + + return useMutation({ + mutationFn: (userId: string) => apiClient.deactivateUser(userId), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['users'] }); + queryClient.invalidateQueries({ queryKey: ['admin', 'stats'] }); + }, + }); +} + +export function useResetUserPassword() { + const queryClient = useQueryClient(); + + return useMutation({ + mutationFn: (userId: string) => apiClient.resetUserPassword(userId), + onSuccess: (_, userId) => { + queryClient.invalidateQueries({ queryKey: ['users', userId] }); + }, + }); +} diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts index fc3cd6a..f3de474 100644 --- a/frontend/src/lib/api.ts +++ b/frontend/src/lib/api.ts @@ -4,6 +4,7 @@ import type { LoginRequest, LoginResponse, RefreshResponse, + MicrosoftLoginResponse, Job, JobCreateRequest, JobListResponse, @@ -14,6 +15,12 @@ import type { BulkDeleteRequest, BulkDeleteResponse, JobDeleteResponse, + User, + UserListResponse, + CreateUserRequest, + UpdateUserRequest, + ResetPasswordResponse, + AdminStatsResponse, } from '../types/api'; const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000'; @@ -97,6 +104,12 @@ class ApiClient { return response.data; } + async loginWithMicrosoft(idToken: string): Promise { + const response = await this.client.post('/auth/microsoft', { id_token: idToken }); + this.setAccessToken(response.data.access_token); + return response.data; + } + async refresh(): Promise { const response = await this.client.post('/auth/refresh'); this.setAccessToken(response.data.access_token); @@ -217,6 +230,53 @@ class ApiClient { const response = await this.client.post(`/admin/maintenance/reprocess-job/${id}`); return response.data; } + + // User Management endpoints + async listUsers(filters?: { + page?: number; + size?: number; + role?: string; + active_only?: boolean; + }): Promise { + const params = new URLSearchParams(); + if (filters?.page) params.append('page', filters.page.toString()); + if (filters?.size) params.append('size', filters.size.toString()); + if (filters?.role) params.append('role', filters.role); + if (filters?.active_only !== undefined) params.append('active_only', filters.active_only.toString()); + + const response = await this.client.get(`/admin/users?${params.toString()}`); + return response.data; + } + + async getUser(userId: string): Promise { + const response = await this.client.get(`/admin/users/${userId}`); + return response.data; + } + + async createUser(data: CreateUserRequest): Promise { + const response = await this.client.post('/admin/users', data); + return response.data; + } + + async updateUser(userId: string, data: UpdateUserRequest): Promise { + const response = await this.client.patch(`/admin/users/${userId}`, data); + return response.data; + } + + async deactivateUser(userId: string): Promise<{ message: string }> { + const response = await this.client.delete(`/admin/users/${userId}`); + return response.data; + } + + async resetUserPassword(userId: string): Promise { + const response = await this.client.post(`/admin/users/${userId}/password/reset`); + return response.data; + } + + async getAdminStats(): Promise { + const response = await this.client.get('/admin/stats'); + return response.data; + } } export const apiClient = new ApiClient(); diff --git a/frontend/src/lib/msalConfig.ts b/frontend/src/lib/msalConfig.ts new file mode 100644 index 0000000..343c832 --- /dev/null +++ b/frontend/src/lib/msalConfig.ts @@ -0,0 +1,100 @@ +/** + * Microsoft Authentication Library (MSAL) Configuration + * + * Configures MSAL for Azure AD authentication with PKCE flow. + * PKCE is automatically enabled for browser-based SPAs. + */ + +import { LogLevel } from '@azure/msal-browser'; +import type { Configuration } from '@azure/msal-browser'; + +/** + * MSAL Configuration + * + * Documentation: https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md + */ +export const msalConfig: Configuration = { + auth: { + clientId: import.meta.env.VITE_AZURE_CLIENT_ID || '', + authority: import.meta.env.VITE_AZURE_AUTHORITY || '', + redirectUri: import.meta.env.VITE_AZURE_REDIRECT_URI || window.location.origin, + postLogoutRedirectUri: import.meta.env.VITE_AZURE_REDIRECT_URI || window.location.origin, + navigateToLoginRequestUrl: false, // We handle navigation ourselves + }, + cache: { + cacheLocation: 'sessionStorage', // More secure than localStorage + storeAuthStateInCookie: false, // Set to true for IE 11 or Edge + }, + system: { + loggerOptions: { + loggerCallback: (level: LogLevel, message: string, containsPii: boolean) => { + if (containsPii) { + return; + } + switch (level) { + case LogLevel.Error: + console.error('[MSAL]', message); + return; + case LogLevel.Info: + console.info('[MSAL]', message); + return; + case LogLevel.Verbose: + console.debug('[MSAL]', message); + return; + case LogLevel.Warning: + console.warn('[MSAL]', message); + return; + } + }, + logLevel: import.meta.env.DEV ? LogLevel.Info : LogLevel.Error, + piiLoggingEnabled: false, + }, + allowNativeBroker: false, // Disable WAM broker (Windows) + windowHashTimeout: 60000, + iframeHashTimeout: 6000, + loadFrameTimeout: 0, + }, +}; + +/** + * Scopes for login request + * + * openid: Required for OIDC + * profile: Get user's display name + * email: Get user's email address + */ +export const loginRequest = { + scopes: ['openid', 'profile', 'email'], +}; + +/** + * Scopes for silent token acquisition + */ +export const tokenRequest = { + scopes: ['openid', 'profile', 'email'], +}; + +/** + * Validate MSAL configuration + * + * Throws error if required environment variables are missing + */ +export function validateMsalConfig(): void { + const clientId = import.meta.env.VITE_AZURE_CLIENT_ID; + const authority = import.meta.env.VITE_AZURE_AUTHORITY; + const redirectUri = import.meta.env.VITE_AZURE_REDIRECT_URI; + + if (!clientId) { + throw new Error('VITE_AZURE_CLIENT_ID is not configured'); + } + + if (!authority) { + throw new Error('VITE_AZURE_AUTHORITY is not configured'); + } + + if (!redirectUri) { + console.warn('VITE_AZURE_REDIRECT_URI is not configured, using window.location.origin'); + } + + console.log('[MSAL] Configuration validated successfully'); +} diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx index ec0d1c0..069306e 100644 --- a/frontend/src/main.tsx +++ b/frontend/src/main.tsx @@ -1,8 +1,18 @@ import { StrictMode } from 'react' import { createRoot } from 'react-dom/client' import * as Sentry from '@sentry/react' +import { PublicClientApplication } from '@azure/msal-browser' +import { MsalProvider } from '@azure/msal-react' import './styles/index.css' import App from './App.tsx' +import { msalConfig, validateMsalConfig } from './lib/msalConfig' + +// Initialize MSAL (Microsoft Authentication Library) +validateMsalConfig(); +const msalInstance = new PublicClientApplication(msalConfig); + +// Initialize MSAL instance +await msalInstance.initialize(); // Initialize Sentry if (import.meta.env.VITE_SENTRY_DSN) { @@ -31,6 +41,8 @@ if (import.meta.env.VITE_SENTRY_DSN) { createRoot(document.getElementById('root')!).render( - + + + , ) diff --git a/frontend/src/routes/Login.tsx b/frontend/src/routes/Login.tsx index b9db1a2..7dab76d 100644 --- a/frontend/src/routes/Login.tsx +++ b/frontend/src/routes/Login.tsx @@ -1,13 +1,18 @@ import { useState } from 'react'; import { useNavigate } from 'react-router-dom'; +import { useMsal } from '@azure/msal-react'; import { useAuthStore } from '../lib/auth'; +import { loginRequest } from '../lib/msalConfig'; +import { apiClient } from '../lib/api'; export function Login() { const [email, setEmail] = useState(''); const [password, setPassword] = useState(''); const [error, setError] = useState(''); + const [microsoftLoading, setMicrosoftLoading] = useState(false); const navigate = useNavigate(); - const { login, isLoading } = useAuthStore(); + const { login, isLoading, setUser } = useAuthStore(); + const { instance } = useMsal(); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); @@ -29,6 +34,50 @@ export function Login() { } }; + const handleMicrosoftLogin = async () => { + setError(''); + setMicrosoftLoading(true); + + try { + // Login with popup + const response = await instance.loginPopup(loginRequest); + + // Get ID token from Microsoft response + const idToken = response.idToken; + + // Send ID token to our backend for validation and user creation + const loginResponse = await apiClient.loginWithMicrosoft(idToken); + + // Set user in auth store + setUser({ + id: loginResponse.user_id, + email: loginResponse.email, + full_name: loginResponse.full_name, + role: loginResponse.role as 'client' | 'reviewer' | 'admin', + auth_provider: loginResponse.auth_provider, + is_active: true, + created_at: new Date().toISOString(), + }); + + console.log('Microsoft login successful'); + navigate('/'); + } catch (err: unknown) { + console.error('Microsoft login failed:', err); + const error = err as { code?: string; response?: { data?: { detail?: string; message?: string } }; message?: string }; + + if (error.code === 'ERR_NETWORK' || !error.response) { + setError('Network error: Cannot connect to server. Please check if the backend is running.'); + } else if (error.message?.includes('user_cancelled') || error.message?.includes('AADB2C90091')) { + // User cancelled the popup - don't show error + setError(''); + } else { + setError(error.response?.data?.detail || error.response?.data?.message || error.message || 'Microsoft authentication failed. Please try again.'); + } + } finally { + setMicrosoftLoading(false); + } + }; + return (
{/* Left side - Branding */} @@ -139,7 +188,7 @@ export function Login() { + {/* Divider */} +
+
+
+
+
+ Or continue with +
+
+ + {/* Microsoft Sign In Button */} + +

Demo Credentials:

diff --git a/frontend/src/routes/admin/UserDetail.tsx b/frontend/src/routes/admin/UserDetail.tsx new file mode 100644 index 0000000..e14ddb2 --- /dev/null +++ b/frontend/src/routes/admin/UserDetail.tsx @@ -0,0 +1,291 @@ +import { useState, useEffect } from 'react'; +import { useParams, useNavigate, Link } from 'react-router-dom'; +import { useUser, useUpdateUser, useResetUserPassword } from '../../hooks/useUsers'; +import { useToastContext } from '../../contexts/ToastContext'; +import type { UserRole, UpdateUserRequest } from '../../types/api'; + +export function UserDetail() { + const { id } = useParams<{ id: string }>(); + const navigate = useNavigate(); + const toast = useToastContext(); + + const { data: user, isLoading, error } = useUser(id!); + const updateUserMutation = useUpdateUser(); + const resetPasswordMutation = useResetUserPassword(); + + const [formData, setFormData] = useState({ + email: '', + full_name: '', + role: 'client' as UserRole, + is_active: true, + }); + + // Initialize form when user data loads + useEffect(() => { + if (user) { + setFormData({ + email: user.email, + full_name: user.full_name, + role: user.role, + is_active: user.is_active, + }); + } + }, [user]); + + if (isLoading) { + return ( +
+
+
+
+
+
+
+
+
+
+ ); + } + + if (error || !user) { + return ( +
+

User Not Found

+
+

Failed to load user details.

+
+ + ← Back to Users + +
+ ); + } + + const handleSubmit = async (e: React.FormEvent) => { + e.preventDefault(); + + try { + await updateUserMutation.mutateAsync({ + userId: id!, + data: formData, + }); + toast.toastOnly.success('User updated successfully'); + navigate('/admin/users'); + } catch (error) { + const errorMessage = error instanceof Error && 'response' in error + ? (error as { response?: { data?: { detail?: string } } }).response?.data?.detail + : undefined; + toast.toastOnly.error(errorMessage || 'Failed to update user'); + } + }; + + const handleResetPassword = async () => { + if (!window.confirm(`Are you sure you want to reset password for ${user.email}?`)) { + return; + } + + try { + const response = await resetPasswordMutation.mutateAsync(id!); + toast.toastOnly.success(`Password reset. Temporary password: ${response.temporary_password}`); + } catch (error) { + const errorMessage = error instanceof Error && 'response' in error + ? (error as { response?: { data?: { detail?: string } } }).response?.data?.detail + : undefined; + toast.toastOnly.error(errorMessage || 'Failed to reset password'); + } + }; + + const hasChanges = + formData.email !== user.email || + formData.full_name !== user.full_name || + formData.role !== user.role || + formData.is_active !== user.is_active; + + return ( +
+
+ + + + + Back to Users + +

Edit User

+
+ +
+ {/* Main Form */} +
+
+
+ + setFormData({ ...formData, email: e.target.value })} + className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500" + /> +
+ +
+ + setFormData({ ...formData, full_name: e.target.value })} + className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500" + /> +
+ +
+ + +
+ +
+ setFormData({ ...formData, is_active: e.target.checked })} + className="rounded border-gray-300 text-blue-600 focus:ring-blue-500" + /> + +
+ +
+ + +
+
+
+ + {/* Sidebar */} +
+ {/* User Info Card */} +
+

User Information

+
+
+
User ID
+
{user.id}
+
+
+
Authentication Method
+
+ + {user.auth_provider === 'microsoft' && ( + + + + )} + {user.auth_provider} + +
+
+
+
Created
+
+ {user.created_at ? new Date(user.created_at).toLocaleString() : 'N/A'} +
+
+
+
Status
+
+ + {user.is_active ? 'Active' : 'Inactive'} + +
+
+
+
+ + {/* Actions Card */} +
+

Actions

+
+ {user.auth_provider === 'local' ? ( + <> + + +
+

+ Note: Resetting a password will generate a temporary password that must be shared with the user securely. +

+
+ + ) : ( +
+
+ + + +
+

Microsoft Authentication

+

+ This user authenticates via Microsoft. Password management is handled by Microsoft Azure AD. +

+
+
+
+ )} +
+
+
+
+
+ ); +} diff --git a/frontend/src/routes/admin/UserList.tsx b/frontend/src/routes/admin/UserList.tsx new file mode 100644 index 0000000..4956030 --- /dev/null +++ b/frontend/src/routes/admin/UserList.tsx @@ -0,0 +1,452 @@ +import { useState } from 'react'; +import { Link } from 'react-router-dom'; +import { + useUsers, + useDeactivateUser, + useResetUserPassword, + useCreateUser, +} from '../../hooks/useUsers'; +import { useToastContext } from '../../contexts/ToastContext'; +import type { UserRole, CreateUserRequest } from '../../types/api'; + +export function UserList() { + const [page, setPage] = useState(1); + const [roleFilter, setRoleFilter] = useState(''); + const [activeOnly, setActiveOnly] = useState(true); + const [showCreateModal, setShowCreateModal] = useState(false); + const toast = useToastContext(); + + const { data: usersResponse, isLoading, error } = useUsers({ + page, + size: 20, + role: roleFilter || undefined, + active_only: activeOnly, + }); + + const deactivateUserMutation = useDeactivateUser(); + const resetPasswordMutation = useResetUserPassword(); + + if (isLoading) { + return ( +
+
+
+
+ {[...Array(5)].map((_, i) => ( +
+ ))} +
+
+
+ ); + } + + if (error) { + return ( +
+

User Management

+
+

Failed to load users. Please try again.

+
+
+ ); + } + + const users = usersResponse?.users || []; + const totalPages = Math.ceil((usersResponse?.total || 0) / 20); + + const handleDeactivateUser = async (userId: string, userEmail: string) => { + if (!window.confirm(`Are you sure you want to deactivate ${userEmail}?`)) { + return; + } + + try { + await deactivateUserMutation.mutateAsync(userId); + toast.toastOnly.success(`User ${userEmail} deactivated successfully`); + } catch (error) { + const errorMessage = error instanceof Error && 'response' in error + ? (error as { response?: { data?: { detail?: string } } }).response?.data?.detail + : undefined; + toast.toastOnly.error(errorMessage || 'Failed to deactivate user'); + } + }; + + const handleResetPassword = async (userId: string, userEmail: string) => { + if (!window.confirm(`Are you sure you want to reset password for ${userEmail}?`)) { + return; + } + + try { + const response = await resetPasswordMutation.mutateAsync(userId); + // Show the temporary password to the admin + toast.toastOnly.success(`Password reset. Temporary password: ${response.temporary_password}`); + } catch (error) { + const errorMessage = error instanceof Error && 'response' in error + ? (error as { response?: { data?: { detail?: string } } }).response?.data?.detail + : undefined; + toast.toastOnly.error(errorMessage || 'Failed to reset password'); + } + }; + + return ( +
+
+

User Management

+ +
+ + {/* Filters */} +
+
+
+ + +
+ +
+ { + setActiveOnly(e.target.checked); + setPage(1); + }} + className="rounded border-gray-300" + /> + +
+ +
+ {usersResponse?.total || 0} user{usersResponse?.total !== 1 ? 's' : ''} found +
+
+
+ + {/* Users List */} + {users.length === 0 ? ( +
+
+ + + +
+

No users found

+

Try adjusting your filters or create a new user.

+
+ ) : ( + <> +
+ + + + + + + + + + + + + {users.map((user) => ( + + + + + + + + + ))} + +
+ User + + Role + + Auth Method + + Status + + Created + + Actions +
+
+
+ + {user.email.charAt(0).toUpperCase()} + +
+
+
{user.full_name}
+
{user.email}
+
+
+ 		+ + {user.role} + + + + {user.auth_provider === 'microsoft' ? ( + + + + ) : null} + {user.auth_provider} + + + + {user.is_active ? 'Active' : 'Inactive'} + + + {user.created_at ? new Date(user.created_at).toLocaleDateString() : 'N/A'} + +
+ + Edit + + {user.auth_provider !== 'microsoft' && ( + + )} + {user.is_active && ( + + )} +
+
+
+ + {/* Pagination */} + {totalPages > 1 && ( +
+
+ + +
+
+
+

+ Showing page {page} of{' '} + {totalPages} +

+
+
+ +
+
+
+ )} + + )} + + {/* Create User Modal */} + {showCreateModal && ( + setShowCreateModal(false)} + onSuccess={() => { + setShowCreateModal(false); + toast.toastOnly.success('User created successfully'); + }} + /> + )} +
+ ); +} + +// Create User Modal Component +function CreateUserModal({ onClose, onSuccess }: { onClose: () => void; onSuccess: () => void }) { + const [formData, setFormData] = useState({ + email: '', + password: '', + full_name: '', + role: 'client' as UserRole, + }); + const createUserMutation = useCreateUser(); + const toast = useToastContext(); + + const handleSubmit = async (e: React.FormEvent) => { + e.preventDefault(); + + try { + await createUserMutation.mutateAsync(formData); + onSuccess(); + } catch (error) { + const errorMessage = error instanceof Error && 'response' in error + ? (error as { response?: { data?: { detail?: string } } }).response?.data?.detail + : undefined; + toast.toastOnly.error(errorMessage || 'Failed to create user'); + } + }; + + return ( +
+
+
+

Create New User

+ +
+ +
+
+ + setFormData({ ...formData, email: e.target.value })} + className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500" + /> +
+ +
+ + setFormData({ ...formData, full_name: e.target.value })} + className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500" + /> +
+ +
+ + setFormData({ ...formData, password: e.target.value })} + className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500" + /> +

Minimum 8 characters

+
+ +
+ + +
+ +
+ + +
+
+
+
+ ); +} diff --git a/frontend/src/types/api.ts b/frontend/src/types/api.ts index 5dc04a8..fa349e0 100644 --- a/frontend/src/types/api.ts +++ b/frontend/src/types/api.ts @@ -12,12 +12,14 @@ export type JobStatus = | "completed"; export type UserRole = "client" | "reviewer" | "admin"; +export type AuthProvider = "local" | "microsoft"; export interface User { id: string; email: string; full_name: string; role: UserRole; + auth_provider: AuthProvider; is_active: boolean; created_at: string; } @@ -102,6 +104,20 @@ export interface RefreshResponse { full_name: string; } +export interface MicrosoftLoginRequest { + id_token: string; +} + +export interface MicrosoftLoginResponse { + access_token: string; + token_type: string; + user_id: string; + role: string; + email: string; + full_name: string; + auth_provider: AuthProvider; +} + export interface JobCreateRequest { title: string; language: string; @@ -148,4 +164,40 @@ export interface BulkDeleteResponse { export interface JobDeleteResponse { message: string; +} + +// User Management types +export interface UserListResponse { + users: User[]; + total: number; + page: number; + size: number; +} + +export interface CreateUserRequest { + email: string; + password: string; + full_name: string; + role: UserRole; +} + +export interface UpdateUserRequest { + email?: string; + full_name?: string; + role?: UserRole; + is_active?: boolean; +} + +export interface ResetPasswordResponse { + message: string; + temporary_password: string; + note: string; +} + +export interface AdminStatsResponse { + total_users: number; + total_jobs: number; + jobs_by_status: Record; + active_jobs_today: number; + avg_processing_time_hours: number; } \ No newline at end of file diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts index 5fda732..a04a9f1 100644 --- a/frontend/vite.config.ts +++ b/frontend/vite.config.ts @@ -5,12 +5,13 @@ import react from '@vitejs/plugin-react' // https://vite.dev/config/ export default defineConfig({ plugins: [react()], - // Base path for production deployment in Apache subdirectory + // Base path: consistent across dev and production base: '/video-accessibility/', server: { + port: 6001, // Local development port proxy: { '/api': { - target: 'http://localhost:8000', + target: 'http://localhost:8003', // Docker container exposed port changeOrigin: true, ws: true, // Enable WebSocket proxying }, diff --git a/scripts/run-local.sh b/scripts/run-local.sh new file mode 100755 index 0000000..df58d64 --- /dev/null +++ b/scripts/run-local.sh @@ -0,0 +1,243 @@ +#!/bin/bash +# ============================================================================= +# Local Development Startup Script for Accessible Video Platform +# ============================================================================= +# This script starts backend services (API, Worker, MongoDB, Redis) in Docker +# Frontend should be run separately: cd frontend && npm run dev +# +# Usage: ./scripts/run-local.sh [options] +# Options: +# --rebuild Force rebuild of Docker images +# --stop Stop all services +# --restart Restart all services +# ============================================================================= + +set -e # Exit on any error + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Configuration +COMPOSE_FILES="-f docker-compose.yml -f docker-compose.local.yml --env-file .env.local" + +# ============================================================================= +# Helper Functions +# ============================================================================= + +print_header() { + echo -e "${BLUE}==============================================================================${NC}" + echo -e "${BLUE}$1${NC}" + echo -e "${BLUE}==============================================================================${NC}" +} + +print_success() { + echo -e "${GREEN}✓ $1${NC}" +} + +print_error() { + echo -e "${RED}✗ $1${NC}" +} + +print_warning() { + echo -e "${YELLOW}⚠ $1${NC}" +} + +print_info() { + echo -e "${BLUE}ℹ $1${NC}" +} + +# ============================================================================= +# Pre-flight Checks +# ============================================================================= + +preflight_checks() { + print_header "Pre-flight Checks" + + # Check if running from correct directory + if [ ! -f "docker-compose.yml" ]; then + print_error "docker-compose.yml not found. Please run from project root." + exit 1 + fi + print_success "Running from correct directory" + + # Check if .env.local exists + if [ ! -f ".env.local" ]; then + print_error ".env.local not found. Please create it first." + print_info "You can copy from .env.prod.example and modify for local settings" + exit 1 + fi + print_success ".env.local found" + + # Check if secrets directory exists + if [ ! -d "secrets" ]; then + print_error "secrets/ directory not found" + exit 1 + fi + print_success "secrets/ directory found" + + # Check if GCP credentials exist + if [ ! -f "secrets/gcp-credentials.json" ]; then + print_error "secrets/gcp-credentials.json not found" + exit 1 + fi + print_success "GCP credentials found" + + # Check if Docker is running + if ! docker info > /dev/null 2>&1; then + print_error "Docker is not running" + exit 1 + fi + print_success "Docker is running" + + # Check if docker compose is available + if ! docker compose version &> /dev/null; then + print_error "docker compose is not installed" + exit 1 + fi + print_success "docker compose is available" + + echo "" +} + +# ============================================================================= +# Stop Services +# ============================================================================= + +stop_services() { + print_header "Stopping Services" + + print_info "Stopping all containers..." + docker compose $COMPOSE_FILES down + print_success "Services stopped" + + echo "" +} + +# ============================================================================= +# Start Services +# ============================================================================= + +start_services() { + print_header "Starting Local Development Services" + + # Load environment variables + export $(cat .env.local | grep -v '^#' | xargs) + + # Build images if needed + if [ "$REBUILD" = true ]; then + print_info "Building Docker images (--rebuild flag specified)..." + docker compose $COMPOSE_FILES build --no-cache + print_success "Docker images built" + fi + + # Start services + print_info "Starting services..." + docker compose $COMPOSE_FILES up -d + print_success "Services started" + + # Wait for services to be healthy + print_info "Waiting for services to be healthy (30 seconds)..." + sleep 30 + + # Check service health + print_info "Checking container status..." + docker compose $COMPOSE_FILES ps + + echo "" +} + +# ============================================================================= +# Display Status and Instructions +# ============================================================================= + +display_status() { + print_header "Local Development Environment Ready" + + echo -e "${GREEN}✓ Backend services are running in Docker${NC}" + echo "" + echo -e "${BLUE}Service URLs:${NC}" + echo " API: http://localhost:8003" + echo " Docs: http://localhost:8003/docs" + echo " MongoDB: mongodb://localhost:27017" + echo " Redis: redis://localhost:6379" + echo "" + echo -e "${YELLOW}Next Steps:${NC}" + echo " 1. Start the frontend:" + echo " ${GREEN}cd frontend && npm run dev${NC}" + echo "" + echo " 2. Access the application:" + echo " ${GREEN}http://localhost:6001/video-accessibility${NC}" + echo "" + echo -e "${BLUE}Useful Commands:${NC}" + echo " View logs: ${GREEN}docker compose logs -f [service]${NC}" + echo " Restart service: ${GREEN}docker compose restart [service]${NC}" + echo " Stop services: ${GREEN}./scripts/run-local.sh --stop${NC}" + echo " Rebuild images: ${GREEN}./scripts/run-local.sh --rebuild${NC}" + echo "" + echo -e "${BLUE}Available services:${NC} api, worker, mongodb, redis" + echo "" +} + +# ============================================================================= +# Main Function +# ============================================================================= + +main() { + # Parse command line arguments + REBUILD=false + STOP=false + RESTART=false + + while [[ $# -gt 0 ]]; do + case $1 in + --rebuild) + REBUILD=true + shift + ;; + --stop) + STOP=true + shift + ;; + --restart) + RESTART=true + shift + ;; + *) + print_error "Unknown option: $1" + echo "Usage: $0 [--rebuild] [--stop] [--restart]" + exit 1 + ;; + esac + done + + print_header "Accessible Video Platform - Local Development" + echo "" + + # Execute based on flags + if [ "$STOP" = true ]; then + preflight_checks + stop_services + print_success "Local development environment stopped" + exit 0 + fi + + if [ "$RESTART" = true ]; then + preflight_checks + stop_services + start_services + display_status + exit 0 + fi + + # Normal startup + preflight_checks + start_services + display_status +} + +# Run main function +main "$@" diff --git a/secrets/gcp-credentials.json b/secrets/gcp-credentials.json new file mode 100644 index 0000000..cf2c07a --- /dev/null +++ b/secrets/gcp-credentials.json @@ -0,0 +1,13 @@ +{ + "type": "service_account", + "project_id": "optical-414516", + "private_key_id": "80e2475f641260d5c28e29d10574cef0ba5bff01", + "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDBPenCel/D+oNr\nf3OZTHsb4GYmqIZpzKLHYsj6/578Oayng0SR8zgAqV1JZSAud3bMFH7tT32Pa6qE\ntB1PNslhgtlYAGa5z9iXDSHksOZ6dAgk2YilZ7deAteGvoeNwkALrxR0FW9Uj0q0\nc1oszSekmpSwzy5QPuQOmt9D1xH+tbX5/zUXxkQmNSKzyPtE/0B5FxdeyoVgK4ZT\nHca6IonDXdW58c9iNdCqboShlb6VZP9zMRMykEuvD9fKMzQUGmjhqI3oGf/B11s9\n+PrtImb9uSrohUVerc/1PjDwA+y/uWet3PGxobFU05GPIbz2sj/nm6Vo1+XDIVgw\nFXSahTdhAgMBAAECggEAC+VTBC6iwcTxXVpVmqF9D25BwfqsRTJC79TcKN3R9haN\nOZKr7SaOOZwzd4n+I5FYtgXc+m1JfkOGfImjjdwCWAcrq6GUSupjAiMQ0kWbKpae\nzOxUErqbxlgucS3X2MyVQyLead1kvE15FjqzpmZkT/Tw8LsQT5uCtoam9kPBgjum\noO0tR6MChkI07LUQ2XXINLLWVbhWLBImksiW9ehcR/htsNMrszSFem6hLe+7PgRq\nxFocz1jt7G/x+csLgyI4cZN1jDv3xd+quxgSgdBZEeOvTWfuTWM+rbMavWzqD2rn\nBpPI1+N1bwNUf0XbKtG6e7WYFUPGGbQjJmLjimAnMQKBgQD7Pdr2fTgek94mvzzb\nnd1Ksri9waf3YJKYchDe5HHtTq+y7IdgFWbmL8ybjKz5TzzHCLt1clg85Fptb14g\noAZxJcS7N1P0uWgHgIWNfm8oFEVmEu2fHfeYjlCPEuroRk6BT9gR7bLwt0mM0mIO\nJJcBbXZyDt4qok/i5r4yeVY2swKBgQDE5tiRjOGq8r5w7q9OMee671g33xw3UcNN\nGlBcbqHnNZZF8+P62ampuHSadsYtOmbQDFbHo7taV7ZhDmtavUU8LQw8TERxj0xQ\nD+p3uCBBQeKPg6h4e2XNjRc6+7riShiCEPwg92M4qpZvlNoGzTogiXiRPBW97Y6z\nacA3Y5oDmwKBgQDodvhF/+DQMiNoGKSX1D6wYiObuDbRJrMdiNVhV2CuoZLibAZq\negMG041vE7/swktLIiJJbm6EkQm2nkgqycaMJNUeIPh2xKKj5mAsZqM1I2R/KN5i\nztiMeInDiE6AcqUq8xTKqfRa1EyilvsRePub34urx2P7cMmX+cZcb3a9DwKBgQCO\nWBxkTKavwMDwP304WFegCnuKGJ77Vv6LdOR3jfs5fMHgXEqKBGTlL1YMfKUT+U5u\nRR1PQgylaReN3rC5bm7o6+AWj0RDnEac8oSce93Fj23MNm/KedrE2KTcnTMjeFFz\nZff/lRiD1L7gd4mOtTq6XudshzVokp5BEchFwpmK1QKBgQC4yrXV4IxIHgCm3mfN\n/rz5iIt6fOGmp07Uv4ZtFcEBQKrWatWMfAAX/lbOGrje9HFNpl5FlYZe/k4ow3O+\ncxXpQOsu9TZdmDJ0YVH6o/+TAPaF/OrMJ8BqrO4J8fJiD0F+y3Ii3pxr9NrH9hjK\n63QAJ9PaA93UVVEbkh98yIOGJA==\n-----END PRIVATE KEY-----\n", + "client_email": "video-accessibility@optical-414516.iam.gserviceaccount.com", + "client_id": "115091905183525974710", + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://oauth2.googleapis.com/token", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/video-accessibility%40optical-414516.iam.gserviceaccount.com", + "universe_domain": "googleapis.com" +}