---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/oliver
- domain/accessibility
- domain/ai
- tech/azure-ad
- tech/celery
- tech/docker
- tech/elevenlabs
- tech/fastapi
- tech/gemini
- tech/mongodb
- tech/python
- tech/react
- tech/redis
- tech/typescript
- type/sop
type: sop
---

# Developer Manual: Accessible Video Processing Platform

## Architecture Overview

The platform follows a microservices-oriented architecture deployed via Docker Compose, separated into frontend, API, and background workers.

### High-Level Diagram

```mermaid
graph TD
    User[User Browser] -->|HTTPS/WS| Frontend[Frontend (React)]
    Frontend -->|REST API| API[FastAPI/Gunicorn]
    Frontend -->|WebSocket| API
    API -->|Task Publish| Redis[(Redis Broker)]
    API -->|Cache/Session| Redis
    API -->|Data Query| MongoDB[(MongoDB)]
    Redis -->|Consume| Worker[Cellery Workers]
    Worker -->|Process| FFmpeg[FFmpeg Worker]
    Worker -->|Process| TTS[TTS Worker]
    Worker -->|Process| Whisper[Whisper Worker]
    Worker -->|Write| MongoDB
```

## Tech Stack

-   **Frontend**: React 18+, TypeScript, Tailwind CSS, React Query, MSAL (Microsoft Authentication).
-   **Backend**: Python, FastAPI, Gunicorn, Celery.
-   **Database**: MongoDB 7.0.
-   **Broker/Cache**: Redis 7.
-   **AI/ML**: Gemini 2.5 Pro (Gemini API), Whisper (Speech-to-Text), Google Cloud TTS, ElevenLabs.
-   **Monitoring**: Sentry (Error/Performance Tracking).
-   **Infrastructure**: Docker, Docker Compose.

## Local Setup

### Prerequisites
-   Docker and Docker Compose.
-   Python 3.10+.
-   Node.js 18+.
-   Google Cloud API Credentials (for Translate, TTS).
-   Google AI Studio API Key (for Gemini).
-   Microsoft Entra ID (Azure AD) App Registration (for MSAL).

### Step 1: Environment Variables
Create a `.env` file in the root directory based on `.env.example`.

```bash
# Database
MONGODB_DB=accessible_video

# Redis
REDIS_URL=redis://redis:6379/0

# AI Services
GEMINI_API_KEY=your_gemini_key
GOOGLE_CLOUD_PROJECT_ID=your_project_id
GOOGLE_APPLICATION_CREDENTIALS=./path/to/key.json

# Auth
MSAL_CLIENT_ID=your_azure_client_id
MSAL_TENANT_ID=your_azure_tenant_id

# Sentry
SENTRY_DSN=your_sentry_dsn
```

### Step 2: Start Infrastructure
```bash
docker-compose up -d mongodb redis
```

### Step 3: Backend Setup
```bash
cd backend
pip install -r requirements.txt
# Copy config if necessary
cp config/mongod.conf.example config/mongod.conf
```

### Step 4: Frontend Setup
```bash
cd frontend
npm install
# Ensure .env.development or .env.local is configured with VITE_API_URL
npm run dev
```

### Step 5: Start Workers
In separate terminal windows:
```bash
# Default Worker
celery -A celery_app worker -Q default,ingest,notify,render -c 4

# Dedicated Workers
celery -A celery_app worker -Q tts -c 8
celery -A celery_app worker -Q ffmpeg -c 1
celery -A celery_app worker -Q whisper -c 1
```

## Environment Variables

| Variable | Description | Required |
| :--- | :--- | :--- |
| `MONGODB_DB` | MongoDB database name | Yes |
| `REDIS_URL` | Redis connection string | Yes |
| `GEMINI_API_KEY` | API key for Gemini 2.5 Pro | Yes |
| `MSAL_CLIENT_ID` | Azure AD Client ID | Yes |
| `MSAL_TENANT_ID` | Azure AD Tenant ID | Yes |
| `SENTRY_DSN` | Sentry Data Source Name | Optional |
| `VITE_APP_ENV` | App environment (dev/prod) | Yes |

## Key Services & Entry Points

### 1. Frontend (`frontend/src/main.tsx`)
-   **Auth**: Initializes MSAL `PublicClientApplication` for Microsoft SSO.
-   **Monitoring**: Initializes Sentry with PII filtering.
-   **State**: Provides global contexts for Toasts, Notifications, and WebSocket connections.

### 2. WebSocket (`frontend/src/contexts/GlobalWebSocketContext.tsx`)
-   Manages real-time job status updates.
-   Uses `useJobStatusWebSocket` hook.
-   Dispatches toast notifications based on `getStatusMessageConfig`.

### 3. Backend API (`backend/app/main.py` inferred)
-   **FastAPI** handles REST requests.
-   **Celery** offloads heavy processing:
    -   `ingest`: Video metadata extraction.
    -   `whisper`: Speech-to-text transcription.
    -   `render`: TTS synthesis and FFmpeg video compositing.
    -   `notify`: WebSocket dispatching.

### 4. Database Models (MongoDB)
-   **Job**: Core entity tracking processing status, assets, and metadata.
-   **User/Client/Reviewer**: RBAC models.
-   **AuditLog**: Immutable log of reviewer actions.

## API Reference

*Note: Full OpenAPI spec available at `/docs` in running API.*

### Authentication
-   **POST /auth/login**: Triggers MSAL redirect flow.
-   **GET /auth/callback**: Handles MSAL token exchange.

### Jobs
-   **POST /jobs**: Create a new accessibility job.
    -   Body: `{ video_id, target_languages, services: ["cc", "ad"] }`
-   **GET /jobs**: List jobs with filters (status, owner).
-   **GET /jobs/{job_id}**: Get job details and progress.

### Quality Control
-   **GET /qc/list**: Get jobs awaiting review.
-   **PUT /qc/{job_id}/approve**: Approve job.
-   **PUT /qc/{job_id}/reject**: Reject job with comments.
-   **PUT /qc/{job_id}/edit-vtt**: Update VTT content.

## Deployment

1.  **Build Images**: Ensure Docker images are up to date.
2.  **Production Env**: Set `VITE_APP_ENV=production` and `SENTRY_DSN`.
3.  **Security**: Ensure `HTTPS` is enforced at the reverse proxy (Nginx/AWS ALB).
4.  **Scale Workers**: Increase concurrency in `docker-compose.yml` or use Kubernetes for horizontal scaling.

## Known Gotchas

1.  **FFmpeg Concurrency**: The `ffmpeg-worker` is configured with `concurrency=1`. Do not scale this worker beyond 1 instance per CPU core to avoid file locking issues.
2.  **TTS Quotas**: Google Cloud TTS and ElevenLabs have rate limits. Monitor usage and implement backoff strategies in the TTS worker.
3.  **WebSocket Reconnects**: The frontend handles auto-reconnects. Ensure the backend WebSocket server is stable; unexpected disconnections may require a manual page refresh if reconnect fails.
4.  **Signed URLs**: Generated download links expire after 24 hours. If a user tries to download later, they must re-request the link from the API.
5.  **MSAL Config**: Ensure `msalConfig.ts` matches the Azure AD redirect URIs exactly, including the `basename` (`/video-accessibility`) if deployed to a sub-path.

## Related
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL]]
- [[01 Projects/ac-helper/DEVELOPER_MANUAL]]
- [[01 Projects/oliver-ai-assistant/DEVELOPER_MANUAL.md]]
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL.md]]
- [[01 Projects/ac-helper/DEVELOPER_MANUAL.md]]
- [[01 Projects/video-accessibility-old/DEVELOPER_MANUAL.md]]
- [[01 Projects/enterprise-ai-hub-nexus/DEVELOPER_MANUAL.md]]
- [[01 Projects/ac-tool/DEVELOPER_MANUAL.md]]