Files
igny8/docs/plans/SOCIALIZER-AND-VIDEO-CREATOR-MODULES.md
2026-02-23 22:47:48 +00:00

1377 lines
66 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Socializer & Video Content Creator — Development Plan
> **Created:** February 22, 2026
> **Target Version:** v2.0.0
> **Status:** Planning
> **Dependencies:** Existing IGNY8 v1.8.4 architecture
---
## Table of Contents
1. [Executive Summary](#1-executive-summary)
2. [Module A: Socializer](#2-module-a-socializer)
3. [Module B: Video Content Creator](#3-module-b-video-content-creator)
4. [Shared Infrastructure](#4-shared-infrastructure)
5. [Self-Hosted GPU Option](#5-self-hosted-gpu-option)
6. [Database Schema (All New Models)](#6-database-schema)
7. [AI Functions (New)](#7-ai-functions)
8. [API Endpoints (New)](#8-api-endpoints)
9. [Frontend Pages (New)](#9-frontend-pages)
10. [Celery Tasks (New)](#10-celery-tasks)
11. [Credit Cost Matrix](#11-credit-cost-matrix)
12. [Development Phases](#12-development-phases)
13. [Risk & Dependency Matrix](#13-risk--dependency-matrix)
---
## 1. Executive Summary
Two new active modules extending the existing content pipeline:
```
CURRENT PIPELINE (v1.8.4):
Keywords → Clusters → Ideas → Tasks → Content → Images → Published (WordPress)
EXTENDED PIPELINE (v2.0.0):
┌→ WordPress (existing)
Keywords → Clusters → Ideas → Tasks → Content → Images ──┼→ Socializer → 5 Platforms
└→ Video Creator → 3+ Platforms
```
### What We're Building
| Module | Purpose | Platforms | AI Involved |
|--------|---------|-----------|-------------|
| **Socializer** | Adapt published content into social posts, schedule across platforms | LinkedIn, Twitter/X, Facebook, Instagram, TikTok | Text adaptation, image resizing/generation, hashtag optimization |
| **Video Creator** | Convert articles into video content, publish to video platforms | YouTube, Instagram Reels, TikTok, YouTube Shorts | Script generation, TTS voiceover, video assembly, thumbnail generation |
### Integration Points with Existing System
| Existing Component | How It's Used |
|--------------------|---------------|
| `Content` model | Source material for both modules |
| `Images` model | Source images for social posts and video thumbnails |
| `AIEngine` | Extended with new functions for social/video generation |
| `ModelRegistry` / `AIModelConfig` | New models registered (TTS, video) |
| `IntegrationProvider` | New providers added (social APIs, video APIs) |
| `CreditService` | All operations are credit-based |
| `AutomationConfig` | New stages 8 (Socializer) and 9 (Video) added to pipeline |
| `NotificationService` | Notifications for publish success/failure |
| `PublishingSettings` | Extended with social + video scheduling rules |
| `Celery Beat` | New scheduled tasks for social posting windows |
---
## 2. Module A: Socializer
### 2.1 Overview
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ SOCIALIZER MODULE │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ CONTENT (Published) │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌────────────────────────────────────────────────┐ │
│ │ AI Adaptation │──►│ Platform-Specific Posts │ │
│ │ Engine │ │ │ │
│ │ │ │ LinkedIn → Professional tone, 1300 chars │ │
│ │ • Tone shift │ │ Twitter/X → Punchy, 280 chars, thread option │ │
│ │ • Length trim │ │ Facebook → Conversational, 500 chars │ │
│ │ • Hashtag gen │ │ Instagram → Visual-first, 2200 chars+30 tags │ │
│ │ • CTA insertion │ │ TikTok → Gen-Z tone, trending hooks │ │
│ └─────────────────┘ └──────────────────────┬─────────────────────────┘ │
│ │ │
│ ┌────────────────────────────────────────┤ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Image Optimizer │ │ Social Calendar │ │
│ │ │ │ │ │
│ │ LinkedIn: 1200 │ │ Best-time slots │ │
│ │ ×627 │ │ Queue management │ │
│ │ Twitter: 1600 │ │ Drag-and-drop │ │
│ │ ×900 │ │ Integrated with │ │
│ │ Facebook: 1200 │ │ content calendar │ │
│ │ ×630 │ └────────┬────────┘ │
│ │ Instagram: 1080 │ │ │
│ │ ×1080 │ ▼ │
│ │ TikTok: 1080 │ ┌─────────────────┐ │
│ │ ×1920 │ │ Platform APIs │ │
│ │ │ │ (OAuth2 + SDK) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
```
### 2.2 Platform API Requirements
| Platform | API | Auth | Post Types | Rate Limits | Developer Access |
|----------|-----|------|------------|-------------|-----------------|
| **LinkedIn** | LinkedIn Marketing API v2 | OAuth 2.0 (3-legged) | Text, Image, Article, Carousel | 100 posts/day | Company page required, app review |
| **Twitter/X** | X API v2 (Free/Basic/Pro) | OAuth 2.0 + PKCE | Tweet, Thread, Image, Poll | 1500 tweets/mo (Free), 3000 (Basic) | Developer account, app approval |
| **Facebook** | Meta Graph API v19 | OAuth 2.0 (Page token) | Text, Photo, Link, Video, Carousel | 200 posts/hr per page | Meta Business verification |
| **Instagram** | Instagram Graph API | OAuth 2.0 (via Facebook) | Photo, Carousel, Reel, Story | 25 API calls/hr per user | Facebook Business account required |
| **TikTok** | TikTok Content Posting API | OAuth 2.0 | Video, Photo | 10k requests/day | TikTok for Developers access |
### 2.3 Features Breakdown
#### A. Content Adaptation (AI)
| Feature | Description | AI Provider | Existing/New |
|---------|-------------|-------------|--------------|
| Tone adaptation | Rewrite content excerpt per platform voice | OpenAI GPT-4o / Anthropic Claude | New AI Function |
| Length optimization | Trim/expand to platform char limits | OpenAI GPT-4o-mini | New AI Function |
| Hashtag generation | Generate relevant, trending hashtags | OpenAI GPT-4o-mini | New AI Function |
| CTA insertion | Add platform-appropriate calls-to-action | OpenAI GPT-4o-mini | Part of adaptation |
| Thread splitting | Break long content into Twitter threads | OpenAI GPT-4o-mini | New AI Function |
| Carousel creation | Split article into carousel slides (IG/LinkedIn) | OpenAI GPT-4o | New AI Function |
| Emoji optimization | Add appropriate emojis per platform norms | Included in adaptation | Part of adaptation |
#### B. Image Optimization
| Feature | Description | AI Provider | Existing/New |
|---------|-------------|-------------|--------------|
| Resize/crop | Resize source images to platform specs | Pillow (local) | New utility |
| Text overlay | Add headline text on images for social | Pillow + custom fonts | New utility |
| Thumbnail generation | Create eye-catching social thumbnails | Runware / DALL-E / Bria | Extend existing |
| Format conversion | Convert to platform-optimal format (WebP/JPG) | Pillow (local) | New utility |
| Carousel image gen | Generate multiple slide images | Runware / DALL-E | Extend existing |
**Platform Image Specs:**
| Platform | Post Image | Story/Reel Cover | Carousel Slide | Max File Size |
|----------|-----------|-------------------|----------------|---------------|
| LinkedIn | 1200×627 | N/A | 1080×1080 | 10 MB |
| Twitter/X | 1600×900 | N/A | N/A | 5 MB |
| Facebook | 1200×630 | 1080×1920 | 1080×1080 | 10 MB |
| Instagram | 1080×1080 | 1080×1920 | 1080×1080 | 8 MB |
| TikTok | 1080×1920 | 1080×1920 | N/A | 72 MB (video) |
#### C. Social Calendar
| Feature | Description |
|---------|-------------|
| Calendar view | Monthly/weekly/daily calendar showing scheduled social posts |
| Best-time scheduling | AI-suggested optimal posting times per platform |
| Drag-and-drop | Reschedule posts by dragging on calendar |
| Queue management | FIFO queue with priority override |
| Integration | Merged view with existing Content Calendar (`/publisher/content-calendar`) |
| Bulk scheduling | Schedule posts for multiple platforms in one action |
| Recurring posts | Evergreen content re-posting on schedule |
#### D. Analytics & Tracking
| Metric | Source | Storage |
|--------|--------|---------|
| Impressions | Platform APIs (delayed) | `SocialPostMetrics` model |
| Clicks | Platform APIs OR UTM + our analytics | `SocialPostMetrics` model |
| Engagement rate | Calculated (likes+comments+shares / impressions) | Computed |
| Best performing platform | Aggregated | Dashboard widget |
| Best posting times | Historical analysis | `SocialAnalytics` model |
### 2.4 User Flow
```
1. Content is published (or approved) in Writer/Publisher
2. User navigates to /socializer/posts (or auto-triggered by automation)
3. AI generates platform-specific versions (all 5 or selected)
├── LinkedIn post (professional tone, image 1200×627)
├── Twitter/X tweet or thread (punchy, image 1600×900)
├── Facebook post (conversational, image 1200×630)
├── Instagram caption + image (1080×1080) or carousel
└── TikTok caption (for image-to-video or article link)
4. User reviews/edits each platform version
5. User schedules posting time (or uses AI-suggested best time)
6. Celery task publishes at scheduled time via platform APIs
7. Engagement metrics fetched periodically (every 6 hours)
```
---
## 3. Module B: Video Content Creator
### 3.1 Overview
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ VIDEO CONTENT CREATOR MODULE │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ CONTENT (Published Article) │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Script Engine │ AI converts article → video script │
│ │ (GPT-4o) │ • Sections with narration text │
│ │ │ • Visual cues per section │
│ │ │ • Timing estimates │
│ └────────┬──────────┘ │
│ │ │
│ ┌─────┴──────┐ │
│ ▼ ▼ │
│ ┌────────┐ ┌──────────┐ │
│ │Short │ │Long Form │ │
│ │Form │ │(YouTube) │ │
│ │30-90s │ │5-15 min │ │
│ └───┬────┘ └────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────┐ │
│ │ TTS Engine │ AI voiceover from script │
│ │ • OpenAI TTS │ • Multiple voices │
│ │ • ElevenLabs (opt) │ • Speed/tone control │
│ │ • Self-hosted Coqui │ • Multi-language │
│ └────────────┬─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ Visual Assembly │ │
│ │ │ │
│ │ • Stock footage search │ Pexels/Pixabay API (free) │
│ │ • Article images │ From existing Images model │
│ │ • AI-generated scenes │ Runware/DALL-E/Stable Diffusion │
│ │ • Text overlays │ Key points, statistics │
│ │ • Transitions │ Fade, slide, zoom │
│ └────────────┬─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ Video Composer │ FFmpeg / MoviePy │
│ │ │ │
│ │ • Merge audio+visuals │ │
│ │ • Add captions/subs │ Burned-in or SRT │
│ │ • Add music (opt) │ Royalty-free background │
│ │ • Render final MP4 │ H.264 / H.265 │
│ │ • Multi-resolution │ 1080p, 720p │
│ └────────────┬─────────────┘ │
│ │ │
│ ┌─────────┼──────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────┐ ┌───────┐ ┌────────┐ │
│ │ YT │ │ Reels │ │ TikTok │ + YouTube Shorts │
│ │Long │ │ Short │ │ Short │ │
│ │form │ │ form │ │ form │ │
│ └──────┘ └───────┘ └────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
```
### 3.2 Platform Requirements
| Platform | Format | Max Duration | Resolution | Max Size | API |
|----------|--------|-------------|------------|----------|-----|
| **YouTube** (long) | MP4 (H.264) | 12 hours | 1920×1080 (16:9) | 256 GB | YouTube Data API v3 |
| **YouTube Shorts** | MP4 (H.264) | 60 seconds | 1080×1920 (9:16) | 256 GB | YouTube Data API v3 |
| **Instagram Reels** | MP4 (H.264) | 90 seconds | 1080×1920 (9:16) | 650 MB | Instagram Graph API |
| **TikTok** | MP4 (H.264) | 10 minutes | 1080×1920 (9:16) | 72 MB | TikTok Content Posting API |
### 3.3 Video Generation Pipeline
#### Stage 1: Script Generation (AI)
| Input | Process | Output |
|-------|---------|--------|
| `Content.content_body` (HTML) | GPT-4o extracts key points, writes narration script | `VideoScript` JSON |
| `Content.meta_description` | Creates hook/intro | Opening section |
| `Content.target_keywords` | SEO optimization for video title/description | Video SEO metadata |
**VideoScript Structure:**
```json
{
"title": "10 Python Tips Every Beginner Should Know",
"description": "SEO-optimized video description...",
"tags": ["python", "programming", "tutorial"],
"sections": [
{
"section_id": 1,
"type": "hook",
"narration": "Did you know that 80% of Python beginners...",
"visual_cue": "animated_text",
"text_overlay": "80% of beginners make this mistake",
"duration_estimate": 5.0
},
{
"section_id": 2,
"type": "intro",
"narration": "In this video, we'll cover 10 essential tips...",
"visual_cue": "title_card",
"text_overlay": "10 Essential Python Tips",
"duration_estimate": 8.0
},
{
"section_id": 3,
"type": "point",
"narration": "Tip number one: Use list comprehensions...",
"visual_cue": "code_snippet",
"text_overlay": "Tip 1: List Comprehensions",
"code_block": "result = [x*2 for x in range(10)]",
"duration_estimate": 20.0
}
],
"total_duration_estimate": 480.0,
"chapter_markers": [
{"time": "0:00", "title": "Introduction"},
{"time": "0:13", "title": "Tip 1: List Comprehensions"}
]
}
```
#### Stage 2: Voiceover (TTS)
| Provider | Model | Quality | Latency | Cost Model | Self-Hostable |
|----------|-------|---------|---------|------------|---------------|
| **OpenAI TTS** | `tts-1` / `tts-1-hd` | Good / High | Fast | $15 / 1M chars (tts-1), $30 (hd) | No |
| **ElevenLabs** | Various | Very High | Medium | $5-$330/mo plans | No |
| **Coqui TTS** | XTTS-v2 | Good | Medium | Free (self-hosted) | **Yes** ✅ |
| **Bark** | Bark | Medium | Slow | Free (self-hosted) | **Yes** ✅ |
| **Piper TTS** | Piper | Good (fast) | Very Fast | Free (self-hosted) | **Yes** ✅ |
#### Stage 3: Visual Asset Assembly
| Asset Type | Source | How |
|-----------|--------|-----|
| Article images | Existing `Images` model | Pull from content |
| AI-generated scenes | Runware / DALL-E / Bria / Stable Diffusion | Generate from visual cues |
| Stock footage | Pexels API / Pixabay API | Free stock video clips |
| Text overlays | Pillow / FFmpeg drawtext | Rendered per section |
| Code snippets | Syntax-highlighted rendering | Pillow + Pygments |
| Background music | Royalty-free library (local) | Bundled tracks |
#### Stage 4: Video Composition
| Component | Technology | Purpose |
|-----------|-----------|---------|
| **FFmpeg** | System binary | Core video encoding, merging, transcoding |
| **MoviePy** | Python library (wraps FFmpeg) | High-level composition API |
| **Pillow** | Python library | Image manipulation, text overlays |
| **pydub** | Python library | Audio manipulation, mixing |
| **Pygments** | Python library | Code syntax highlighting for tech content |
**Render Presets:**
| Preset | Resolution | Aspect | Duration | Use Case |
|--------|-----------|--------|----------|----------|
| `youtube_long` | 1920×1080 | 16:9 | 3-15 min | YouTube main video |
| `youtube_short` | 1080×1920 | 9:16 | 30-60s | YouTube Shorts |
| `instagram_reel` | 1080×1920 | 9:16 | 30-90s | Instagram Reels |
| `tiktok` | 1080×1920 | 9:16 | 30-180s | TikTok |
#### Stage 5: Video SEO & Publishing
| Feature | Description |
|---------|-------------|
| Title optimization | AI-generated SEO titles per platform |
| Description | Keyword-rich descriptions with timestamps (YouTube) |
| Tags | AI-extracted relevant tags from content |
| Thumbnails | AI-generated eye-catching thumbnails |
| Captions/Subtitles | Auto-generated SRT from TTS transcript |
| Chapter markers | YouTube chapters from script sections |
### 3.4 User Flow
```
1. Content is published (or user manually selects content)
2. User navigates to /video/create (or auto-triggered by automation)
3. Select video type: Short-form (Reels/Shorts/TikTok) or Long-form (YouTube)
4. AI generates video script → User reviews/edits script
5. Select voice (from TTS provider voice list)
6. Generate voiceover (TTS) → Preview/re-generate
7. AI assembles visuals (images + stock + overlays)
8. Render final video → Preview
9. Optimize SEO metadata (title, description, tags)
10. Schedule/publish to selected platform(s)
11. Track views, engagement (fetched from platform APIs)
```
---
## 4. Shared Infrastructure
### 4.1 New Integration Providers
Add to `IntegrationProvider` table:
| provider_id | display_name | provider_type | Purpose |
|-------------|-------------|---------------|---------|
| `linkedin` | LinkedIn | social | OAuth tokens, Company Page ID |
| `twitter` | Twitter/X | social | OAuth tokens, API keys |
| `facebook` | Facebook/Meta | social | Page tokens, App credentials |
| `instagram` | Instagram | social | Linked via Facebook, IG Business Account ID |
| `tiktok` | TikTok | social | OAuth tokens, Creator credentials |
| `youtube` | YouTube | video | OAuth tokens, Channel ID |
| `elevenlabs` | ElevenLabs | ai | API key for TTS |
| `pexels` | Pexels | stock | API key for stock video/images |
| `pixabay` | Pixabay | stock | API key for stock video/images |
| `gpu_server` | Self-Hosted GPU | ai | URL + auth for custom GPU inference |
### 4.2 New AIModelConfig Entries
| model_name | model_type | provider | Purpose |
|-----------|-----------|----------|---------|
| `tts-1` | tts | openai | Standard TTS voice |
| `tts-1-hd` | tts | openai | High-quality TTS voice |
| `eleven-multilingual-v2` | tts | elevenlabs | Premium TTS (optional) |
| `coqui-xtts-v2` | tts | gpu_server | Self-hosted TTS |
| `piper-en-us` | tts | gpu_server | Self-hosted fast TTS |
| `stable-diffusion-xl` | image | gpu_server | Self-hosted image gen |
| `llama-3.1-70b` | text | gpu_server | Self-hosted text gen |
### 4.3 File Storage
New requirement: **video and audio file storage**.
| Option | For Development | For Production |
|--------|----------------|----------------|
| **Local filesystem** | `MEDIA_ROOT/videos/`, `MEDIA_ROOT/audio/` | Not recommended |
| **S3-compatible** | MinIO (local Docker) | AWS S3 / DigitalOcean Spaces / Cloudflare R2 |
| **CDN** | Not needed | CloudFront / Bunny CDN (for video delivery) |
**Recommended:** Add `django-storages` with S3 backend. All video/audio files stored in S3 with CDN for delivery.
```python
# settings.py additions
DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'
AWS_STORAGE_BUCKET_NAME = 'igny8-media'
AWS_S3_REGION_NAME = 'us-east-1'
MEDIA_URL = 'https://cdn.igny8.com/media/'
```
### 4.4 Extended Automation Pipeline
Current 7-stage pipeline extended to 9:
| Stage | Name | Module | New? |
|-------|------|--------|------|
| 1 | Keywords → Clusters | Planner | Existing |
| 2 | Clusters → Ideas | Planner | Existing |
| 3 | Ideas → Tasks | Writer | Existing |
| 4 | Tasks → Content | Writer | Existing |
| 5 | Content → Image Prompts | Writer | Existing |
| 6 | Image Prompts → Images | Writer | Existing |
| 7 | Review → Published | Publisher | Existing |
| **8** | **Published → Social Posts** | **Socializer** | **NEW** |
| **9** | **Published → Video** | **Video Creator** | **NEW** |
New fields on `AutomationConfig`:
```python
# Stage 8 - Socializer
stage_8_enabled = BooleanField(default=False)
stage_8_platforms = JSONField(default=list) # ["linkedin", "twitter", "facebook"]
stage_8_batch_size = IntegerField(default=5)
max_social_posts_per_run = IntegerField(default=20)
# Stage 9 - Video Creator
stage_9_enabled = BooleanField(default=False)
stage_9_video_type = CharField(default='short') # short / long / both
stage_9_batch_size = IntegerField(default=2)
max_videos_per_run = IntegerField(default=5)
```
---
## 5. Self-Hosted GPU Option
### 5.1 Architecture
```
┌─────────────────────────────────────────────────────────────────────────┐
│ IGNY8 APP SERVER │
│ (Django + Celery Workers) │
└───────────────────────────┬─────────────────────────────────────────────┘
┌─────────────┼─────────────────────┐
▼ ▼ ▼
┌────────────┐ ┌─────────────┐ ┌────────────────┐
│ OpenAI │ │ Anthropic │ │ GPU Server │
│ Cloud API │ │ Cloud API │ │ (Self-Hosted) │
│ │ │ │ │ │
│ GPT-4o │ │ Claude 3.5 │ │ vLLM API │
│ DALL-E 3 │ │ │ │ ├ Llama 3.1 │
│ TTS-1 │ │ │ │ ├ Mistral │
└────────────┘ └─────────────┘ │ ComfyUI API │
│ ├ SDXL │
│ ├ FLUX │
│ Coqui TTS │
│ ├ XTTS-v2 │
└────────────────┘
```
### 5.2 GPU Server Stack
| Component | Purpose | GPU VRAM Needed | Docker Image |
|-----------|---------|----------------|--------------|
| **vLLM** | Text generation (Llama, Mistral) | 40 GB (70B) / 16 GB (7B) | `vllm/vllm-openai` |
| **ComfyUI** | Image generation (SDXL, FLUX) | 12-24 GB | `comfyanonymous/comfyui` |
| **Coqui TTS** | Voice synthesis (XTTS-v2) | 4-6 GB | `ghcr.io/coqui-ai/tts` |
| **Piper TTS** | Fast TTS (lower quality) | 1 GB (CPU ok) | `rhasspy/piper` |
| **Whisper** | Speech-to-text (for captioning) | 4-10 GB | `openai/whisper` |
**Minimum GPU requirement:** 1× NVIDIA A100 80GB or 2× NVIDIA RTX 4090 (24GB each)
**Budget option:** 1× NVIDIA RTX 4090 running 7B text + SDXL + Coqui TTS
### 5.3 GPU Server Integration with ModelRegistry
```python
# New provider type in IntegrationProvider
IntegrationProvider.objects.create(
provider_id='gpu_server',
display_name='Self-Hosted GPU Server',
provider_type='ai',
api_endpoint='https://gpu.igny8.internal:8000',
api_key='internal-auth-token',
config={
'vllm_base_url': 'http://gpu:8000/v1', # OpenAI-compatible
'comfyui_base_url': 'http://gpu:8188', # ComfyUI API
'tts_base_url': 'http://gpu:5002', # Coqui TTS API
'piper_base_url': 'http://gpu:10200', # Piper TTS API
}
)
# ModelRegistry already supports this — just add AIModelConfig entries
# vLLM serves an OpenAI-compatible API, so existing OpenAI client code reuses
```
### 5.4 Fallback Strategy
```
Request → Check gpu_server availability
┌─────────┴──────────┐
│ GPU Online │ GPU Offline/Overloaded
▼ ▼
Use self-hosted Fallback to cloud
(zero API cost) (OpenAI/Anthropic)
```
Implementation: `ModelRegistry.get_model()` checks `IntegrationProvider.is_active` and a health-check endpoint before routing.
---
## 6. Database Schema
### 6.1 Socializer Models
**File:** `backend/igny8_core/business/socializer/models.py`
```python
class SocialAccount(AccountBaseModel):
"""Connected social media accounts"""
platform = CharField(max_length=20, choices=SOCIAL_PLATFORMS)
# linkedin, twitter, facebook, instagram, tiktok
platform_user_id = CharField(max_length=255)
platform_username = CharField(max_length=255)
platform_page_name = CharField(max_length=255, blank=True)
access_token = TextField() # Encrypted
refresh_token = TextField(blank=True) # Encrypted
token_expires_at = DateTimeField(null=True)
scopes = JSONField(default=list)
is_active = BooleanField(default=True)
connected_at = DateTimeField(auto_now_add=True)
last_used_at = DateTimeField(null=True)
metadata = JSONField(default=dict) # Platform-specific data
class SocialPost(SiteSectorBaseModel):
"""A social media post for a specific platform"""
content = ForeignKey('writer.Content', on_delete=CASCADE, related_name='social_posts')
social_account = ForeignKey(SocialAccount, on_delete=CASCADE)
platform = CharField(max_length=20, choices=SOCIAL_PLATFORMS)
# Content
post_text = TextField()
hashtags = JSONField(default=list)
link_url = URLField(blank=True)
call_to_action = CharField(max_length=255, blank=True)
post_type = CharField(max_length=20)
# text, image, carousel, video, thread, story
# Media
media_urls = JSONField(default=list) # URLs of attached images/videos
thumbnail_url = URLField(blank=True)
# Scheduling
status = CharField(max_length=20, choices=SOCIAL_POST_STATUS)
# draft, scheduled, publishing, published, failed, cancelled
scheduled_at = DateTimeField(null=True)
published_at = DateTimeField(null=True)
platform_post_id = CharField(max_length=255, blank=True)
platform_post_url = URLField(blank=True)
error_message = TextField(blank=True)
# AI Generation
ai_model_used = CharField(max_length=100, blank=True)
credits_used = DecimalField(max_digits=10, decimal_places=2, default=0)
created_at = DateTimeField(auto_now_add=True)
updated_at = DateTimeField(auto_now=True)
class SocialPostMetrics(models.Model):
"""Engagement metrics for a published social post"""
social_post = OneToOneField(SocialPost, on_delete=CASCADE, related_name='metrics')
impressions = IntegerField(default=0)
reach = IntegerField(default=0)
likes = IntegerField(default=0)
comments = IntegerField(default=0)
shares = IntegerField(default=0)
clicks = IntegerField(default=0)
saves = IntegerField(default=0)
engagement_rate = DecimalField(max_digits=5, decimal_places=2, default=0)
last_fetched_at = DateTimeField(null=True)
raw_data = JSONField(default=dict) # Full API response
class SocialCalendarSlot(AccountBaseModel):
"""Preferred posting times per platform per site"""
site = ForeignKey('auth.Site', on_delete=CASCADE)
platform = CharField(max_length=20, choices=SOCIAL_PLATFORMS)
day_of_week = IntegerField() # 0=Monday, 6=Sunday
time_slot = TimeField()
is_active = BooleanField(default=True)
```
### 6.2 Video Creator Models
**File:** `backend/igny8_core/business/video/models.py`
```python
class VideoProject(SiteSectorBaseModel):
"""A video project derived from content"""
content = ForeignKey('writer.Content', on_delete=CASCADE, related_name='video_projects')
title = CharField(max_length=500)
description = TextField(blank=True)
# Configuration
video_type = CharField(max_length=20, choices=VIDEO_TYPES)
# youtube_long, youtube_short, instagram_reel, tiktok
target_duration = IntegerField(help_text="Target duration in seconds")
voice_id = CharField(max_length=100, blank=True)
tts_provider = CharField(max_length=50, default='openai')
background_music = CharField(max_length=255, blank=True)
# Script
script = JSONField(default=dict) # VideoScript structure
script_status = CharField(max_length=20, default='pending')
# pending, generating, ready, approved
# Status
status = CharField(max_length=20, choices=VIDEO_STATUS)
# draft, script_ready, generating_audio, generating_visuals,
# composing, rendering, ready, published, failed
progress_pct = IntegerField(default=0)
error_message = TextField(blank=True)
# Output
video_url = URLField(blank=True) # S3/CDN URL of final video
thumbnail_url = URLField(blank=True)
subtitle_url = URLField(blank=True) # SRT file URL
duration_seconds = IntegerField(null=True)
file_size_bytes = BigIntegerField(null=True)
resolution = CharField(max_length=20, blank=True) # 1920x1080
# AI/Credits
ai_model_used = CharField(max_length=100, blank=True)
tts_model_used = CharField(max_length=100, blank=True)
credits_used = DecimalField(max_digits=10, decimal_places=2, default=0)
created_at = DateTimeField(auto_now_add=True)
updated_at = DateTimeField(auto_now=True)
class VideoAsset(models.Model):
"""Individual assets used in a video project"""
project = ForeignKey(VideoProject, on_delete=CASCADE, related_name='assets')
asset_type = CharField(max_length=20)
# voiceover, image, stock_video, text_overlay, music, subtitle
section_id = IntegerField(null=True) # Maps to script section
file_url = URLField()
duration_seconds = DecimalField(max_digits=8, decimal_places=2, null=True)
position = IntegerField(default=0) # Order in sequence
metadata = JSONField(default=dict)
created_at = DateTimeField(auto_now_add=True)
class VideoPublishRecord(AccountBaseModel):
"""Publishing record for a video to a platform"""
project = ForeignKey(VideoProject, on_delete=CASCADE, related_name='publish_records')
site = ForeignKey('auth.Site', on_delete=CASCADE)
platform = CharField(max_length=20)
# youtube, instagram, tiktok
platform_video_id = CharField(max_length=255, blank=True)
platform_url = URLField(blank=True)
status = CharField(max_length=20)
# pending, uploading, processing, published, failed
seo_title = CharField(max_length=500, blank=True)
seo_description = TextField(blank=True)
seo_tags = JSONField(default=list)
chapter_markers = JSONField(default=list)
published_at = DateTimeField(null=True)
error_message = TextField(blank=True)
metadata = JSONField(default=dict)
class VideoMetrics(models.Model):
"""Video performance metrics from platform APIs"""
publish_record = OneToOneField(VideoPublishRecord, on_delete=CASCADE, related_name='metrics')
views = IntegerField(default=0)
likes = IntegerField(default=0)
comments = IntegerField(default=0)
shares = IntegerField(default=0)
watch_time_seconds = IntegerField(default=0)
average_view_duration = DecimalField(max_digits=8, decimal_places=2, default=0)
click_through_rate = DecimalField(max_digits=5, decimal_places=2, default=0)
last_fetched_at = DateTimeField(null=True)
raw_data = JSONField(default=dict)
```
### 6.3 Model Count Impact
| Current (v1.8.4) | New Models | New Total |
|-------------------|-----------|-----------|
| 52+ models | +8 (Socializer: 4, Video: 4) | 60+ models |
---
## 7. AI Functions
### 7.1 New AI Functions
**Location:** `backend/igny8_core/ai/functions/`
| Function | File | Input | Output | Provider |
|----------|------|-------|--------|----------|
| `AdaptContentForSocial` | `social.py` | Content + platform | Platform-specific post text | GPT-4o-mini / Claude |
| `GenerateHashtags` | `social.py` | Content + platform | Hashtag list | GPT-4o-mini |
| `GenerateTwitterThread` | `social.py` | Content | Thread of tweets | GPT-4o |
| `GenerateCarouselSlides` | `social.py` | Content | Slide texts + prompts | GPT-4o |
| `GenerateVideoScript` | `video.py` | Content + video_type | VideoScript JSON | GPT-4o |
| `GenerateVideoSEO` | `video.py` | VideoScript + platform | Title, desc, tags | GPT-4o-mini |
| `GenerateVideoThumbnailPrompt` | `video.py` | VideoScript | Image prompt for thumbnail | GPT-4o-mini |
### 7.2 New Non-AI Processing Functions
| Function | File | Input | Output | Technology |
|----------|------|-------|--------|------------|
| `TextToSpeech` | `tts.py` | Script narration text | Audio MP3/WAV | OpenAI TTS / ElevenLabs / Coqui |
| `ResizeImageForPlatform` | `image_processing.py` | Image + platform specs | Resized image | Pillow |
| `RenderTextOverlay` | `image_processing.py` | Image + text | Image with text | Pillow |
| `ComposeVideo` | `video_composer.py` | Assets (audio, images, overlays) | MP4 video | FFmpeg / MoviePy |
| `GenerateSubtitles` | `subtitle.py` | TTS audio + script | SRT file | Whisper / text-alignment |
| `FetchStockVideo` | `stock.py` | Search query | Video clip URL | Pexels / Pixabay API |
### 7.3 Registration in AIEngine
```python
# ai/engine.py — extend AIEngine
class AIEngine:
# Existing
def auto_cluster(self, keywords): ...
def generate_ideas(self, cluster): ...
def generate_content(self, task): ...
def generate_images(self, content): ...
# NEW — Socializer
def adapt_for_social(self, content, platform, social_account): ...
def generate_hashtags(self, content, platform): ...
def generate_thread(self, content): ...
def generate_carousel(self, content): ...
# NEW — Video Creator
def generate_video_script(self, content, video_type): ...
def generate_voiceover(self, script, voice_id, provider): ...
def compose_video(self, project): ...
def generate_video_seo(self, project, platform): ...
```
---
## 8. API Endpoints
### 8.1 Socializer Endpoints
**Base:** `/api/v1/socializer/`
| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| **Accounts** | | | |
| GET | `/accounts/` | `SocialAccountViewSet.list` | List connected social accounts |
| POST | `/accounts/connect/` | `SocialAccountViewSet.connect` | Start OAuth flow for platform |
| POST | `/accounts/{id}/disconnect/` | `SocialAccountViewSet.disconnect` | Disconnect account |
| POST | `/accounts/{id}/refresh/` | `SocialAccountViewSet.refresh_token` | Refresh OAuth token |
| **Posts** | | | |
| GET | `/posts/` | `SocialPostViewSet.list` | List social posts (filterable) |
| POST | `/posts/generate/` | `SocialPostViewSet.generate` | AI-generate posts for content |
| PUT | `/posts/{id}/` | `SocialPostViewSet.update` | Edit post text/media |
| POST | `/posts/{id}/schedule/` | `SocialPostViewSet.schedule` | Schedule for publishing |
| POST | `/posts/{id}/publish-now/` | `SocialPostViewSet.publish_now` | Publish immediately |
| POST | `/posts/{id}/cancel/` | `SocialPostViewSet.cancel` | Cancel scheduled post |
| POST | `/posts/bulk-generate/` | `SocialPostViewSet.bulk_generate` | Generate for multiple contents |
| POST | `/posts/bulk-schedule/` | `SocialPostViewSet.bulk_schedule` | Schedule multiple posts |
| **Calendar** | | | |
| GET | `/calendar/` | `SocialCalendarViewSet.list` | Get calendar events (date range) |
| GET | `/calendar/slots/` | `SocialCalendarViewSet.slots` | Get configured time slots |
| PUT | `/calendar/slots/` | `SocialCalendarViewSet.update_slots` | Update time slots |
| **Analytics** | | | |
| GET | `/analytics/overview/` | `SocialAnalyticsViewSet.overview` | Aggregated metrics |
| GET | `/analytics/platform/{platform}/` | `SocialAnalyticsViewSet.by_platform` | Per-platform metrics |
| GET | `/analytics/post/{id}/` | `SocialAnalyticsViewSet.by_post` | Single post metrics |
### 8.2 Video Creator Endpoints
**Base:** `/api/v1/video/`
| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| **Projects** | | | |
| GET | `/projects/` | `VideoProjectViewSet.list` | List video projects |
| POST | `/projects/` | `VideoProjectViewSet.create` | Create project from content |
| GET | `/projects/{id}/` | `VideoProjectViewSet.retrieve` | Get project detail |
| DELETE | `/projects/{id}/` | `VideoProjectViewSet.destroy` | Delete project + assets |
| **Script** | | | |
| POST | `/projects/{id}/generate-script/` | `VideoProjectViewSet.generate_script` | AI-generate video script |
| PUT | `/projects/{id}/script/` | `VideoProjectViewSet.update_script` | Edit script manually |
| POST | `/projects/{id}/approve-script/` | `VideoProjectViewSet.approve_script` | Approve script for production |
| **Production** | | | |
| POST | `/projects/{id}/generate-voiceover/` | `VideoProjectViewSet.generate_voiceover` | Generate TTS audio |
| POST | `/projects/{id}/generate-visuals/` | `VideoProjectViewSet.generate_visuals` | Generate/collect visual assets |
| POST | `/projects/{id}/compose/` | `VideoProjectViewSet.compose` | Render final video |
| POST | `/projects/{id}/regenerate-section/{section_id}/` | `VideoProjectViewSet.regenerate_section` | Re-do a specific section |
| **Publishing** | | | |
| POST | `/projects/{id}/publish/` | `VideoProjectViewSet.publish` | Publish to platform(s) |
| GET | `/projects/{id}/publish-status/` | `VideoProjectViewSet.publish_status` | Check publishing status |
| **Assets & Voices** | | | |
| GET | `/voices/` | `VoiceViewSet.list` | List available TTS voices |
| GET | `/projects/{id}/assets/` | `VideoAssetViewSet.list` | List project assets |
| **Analytics** | | | |
| GET | `/analytics/overview/` | `VideoAnalyticsViewSet.overview` | Aggregated video metrics |
| GET | `/analytics/project/{id}/` | `VideoAnalyticsViewSet.by_project` | Single video metrics |
---
## 9. Frontend Pages
### 9.1 New Routes
```
├── SOCIALIZER
│ /socializer/dashboard → Social Dashboard (overview, metrics)
│ /socializer/accounts → Connected Accounts (manage OAuth)
│ /socializer/posts → Social Posts (list, filter, bulk actions)
│ /socializer/posts/:id → Post Detail (edit, preview per platform)
│ /socializer/calendar → Social Calendar (scheduling view)
│ /socializer/analytics → Social Analytics (engagement dashboard)
├── VIDEO CREATOR
│ /video/dashboard → Video Dashboard (overview, metrics)
│ /video/projects → Video Projects (list)
│ /video/create → New Video (select content, configure)
│ /video/projects/:id → Video Project Detail (script, preview, publish)
│ /video/projects/:id/editor → Video Editor (timeline, preview)
│ /video/analytics → Video Analytics
```
### 9.2 New Zustand Stores
| Store | File | Purpose |
|-------|------|---------|
| `socialStore` | `store/socialStore.ts` | Social accounts, posts, calendar state |
| `videoStore` | `store/videoStore.ts` | Video projects, rendering state, voices |
### 9.3 New Components
| Component | Purpose |
|-----------|---------|
| `SocialPostPreview` | Platform-mockup preview (shows how post will look) |
| `SocialCalendar` | Calendar widget for scheduling |
| `PlatformSelector` | Multi-select for target platforms |
| `VideoTimeline` | Timeline editor showing sections, audio, visuals |
| `VideoPlayer` | In-app video preview player |
| `ScriptEditor` | Editable script with section management |
| `VoiceSelector` | TTS voice selector with audio samples |
### 9.4 Sidebar Navigation Updates
```
Current: New:
───────── ─────────
Dashboard Dashboard
Planner Planner
Keywords Keywords
Clusters Clusters
Ideas Ideas
Writer Writer
Tasks Tasks
Content Content
Images Images
Review Review
Automation Automation
Publisher Publisher
Socializer ← NEW
Dashboard
Posts
Calendar
Analytics
Video Creator ← NEW
Dashboard
Projects
Analytics
```
---
## 10. Celery Tasks
### 10.1 Socializer Tasks
| Task | Schedule | Purpose |
|------|----------|---------|
| `socializer.publish_scheduled_posts` | Every 5 min | Publish posts where `scheduled_at <= now` |
| `socializer.refresh_expired_tokens` | Every 6 hours | Refresh OAuth tokens nearing expiration |
| `socializer.fetch_post_metrics` | Every 6 hours | Fetch engagement metrics for published posts |
| `socializer.cleanup_failed_posts` | Daily at 3 AM | Retry or mark stale failed posts |
### 10.2 Video Creator Tasks
| Task | Schedule | Purpose |
|------|----------|---------|
| `video.process_video_project` | On-demand (triggered) | Full pipeline: script → TTS → visuals → compose |
| `video.generate_voiceover` | On-demand | Generate TTS audio for a project |
| `video.compose_video` | On-demand | Render final video (CPU/GPU intensive) |
| `video.publish_video` | On-demand | Upload video to platform |
| `video.fetch_video_metrics` | Every 12 hours | Fetch view/engagement metrics |
| `video.cleanup_temp_assets` | Daily at 4 AM | Remove temporary render files |
### 10.3 Celery Worker Configuration
Video rendering is CPU/GPU intensive — use a separate queue:
```python
# celery.py additions
CELERY_TASK_ROUTES = {
'igny8_core.business.video.tasks.compose_video': {'queue': 'video_render'},
'igny8_core.business.video.tasks.generate_voiceover': {'queue': 'video_render'},
'igny8_core.business.socializer.tasks.*': {'queue': 'social'},
# Existing tasks stay on 'default' queue
}
# docker-compose additions
# worker-video:
# command: celery -A igny8_core worker -Q video_render --concurrency=2
# worker-social:
# command: celery -A igny8_core worker -Q social --concurrency=4
```
---
## 11. Credit Cost Matrix
### 11.1 Socializer Operations
| Operation | AI Model | Est. Tokens | Credits | Notes |
|-----------|----------|------------|---------|-------|
| Adapt content for 1 platform | GPT-4o-mini | ~500 | 1 | Per platform |
| Generate hashtags | GPT-4o-mini | ~200 | 0.5 | Per platform |
| Generate Twitter thread | GPT-4o-mini | ~1000 | 2 | Full thread |
| Generate carousel slides | GPT-4o | ~2000 | 5 | Per carousel |
| Generate social image | Runware/DALL-E | N/A | 3-10 | Per image |
| **Full social suite (5 platforms)** | Mixed | ~5000 | **~15-25** | Per content item |
### 11.2 Video Creator Operations
| Operation | Model/Tool | Est. Usage | Credits | Notes |
|-----------|-----------|------------|---------|-------|
| Generate video script | GPT-4o | ~3000 tokens | 5 | Per script |
| Generate TTS voiceover | OpenAI TTS-1 | ~5000 chars | 10 | Per minute audio |
| Generate TTS voiceover (HD) | OpenAI TTS-1-HD | ~5000 chars | 20 | Per minute audio |
| Generate TTS (self-hosted) | Coqui XTTS | ~5000 chars | 2 | Reduced (own GPU) |
| Generate visual assets | Runware/DALL-E | ~5 images | 15-50 | Per video |
| Generate thumbnail | DALL-E/Runware | 1 image | 3-10 | Per video |
| Video composition | FFmpeg | CPU time | 5 | Per render |
| Video SEO metadata | GPT-4o-mini | ~500 tokens | 1 | Per platform |
| **Full short-form video** | Mixed | - | **~40-80** | 30-60s video |
| **Full long-form video** | Mixed | - | **~100-250** | 5-15 min video |
### 11.3 Self-Hosted GPU Savings
| Operation | Cloud Cost (credits) | Self-Hosted (credits) | Saving |
|-----------|---------------------|----------------------|--------|
| TTS voiceover (1 min) | 10-20 | 2 | 80-90% |
| Image generation (per image) | 5-10 | 1 | 80-90% |
| Text generation (per 1K tokens) | 1-3 | 0.5 | 50-83% |
> Credits for self-hosted operations are lower because there's no API cost—only a flat infrastructure fee per account or globally amortized.
---
## 12. Development Phases
### Phase 1: Foundation (Weeks 1-3)
| # | Task | Type | Effort | Dependencies |
|---|------|------|--------|-------------|
| 1.1 | Add `django-storages` + S3 config for media | Backend infra | 2 days | S3 bucket provisioned |
| 1.2 | Create `SocialAccount`, `SocialPost`, `SocialPostMetrics`, `SocialCalendarSlot` models + migrations | Backend models | 2 days | None |
| 1.3 | Create `VideoProject`, `VideoAsset`, `VideoPublishRecord`, `VideoMetrics` models + migrations | Backend models | 2 days | 1.1 |
| 1.4 | Add new `IntegrationProvider` entries (social, video, GPU) | Backend seed data | 0.5 days | None |
| 1.5 | Add new `AIModelConfig` entries (TTS models, GPU models) | Backend seed data | 0.5 days | None |
| 1.6 | Extend `AutomationConfig` with stage 8 & 9 fields + migration | Backend models | 1 day | None |
| 1.7 | Add FFmpeg + MoviePy + pydub to `requirements.txt` and Dockerfile | Backend infra | 1 day | None |
| 1.8 | Create backend module scaffolding (`modules/socializer/`, `modules/video/`, `business/socializer/`, `business/video/`) | Backend structure | 1 day | None |
| 1.9 | Admin registration for all new models | Backend admin | 1 day | 1.2, 1.3 |
### Phase 2: Socializer — Core (Weeks 3-6)
| # | Task | Type | Effort | Dependencies |
|---|------|------|--------|-------------|
| 2.1 | OAuth2 flow for LinkedIn, Twitter/X, Facebook/Instagram, TikTok | Backend auth | 5 days | Platform developer accounts |
| 2.2 | `AdaptContentForSocial` AI function + prompt templates | Backend AI | 2 days | None |
| 2.3 | `GenerateHashtags` AI function | Backend AI | 1 day | None |
| 2.4 | `GenerateTwitterThread` AI function | Backend AI | 1 day | None |
| 2.5 | Image resizing utility (Pillow) for all platform specs | Backend utility | 2 days | None |
| 2.6 | SocialPost CRUD ViewSet + serializers | Backend API | 2 days | 1.2 |
| 2.7 | Social post publishing service (per-platform SDK wrappers) | Backend service | 5 days | 2.1 |
| 2.8 | `publish_scheduled_posts` Celery task | Backend task | 1 day | 2.7 |
| 2.9 | `fetch_post_metrics` Celery task | Backend task | 2 days | 2.7 |
| 2.10 | Social Calendar API endpoints | Backend API | 2 days | 1.2 |
| 2.11 | Frontend: Social accounts page (OAuth connect/disconnect) | Frontend | 3 days | 2.1 |
| 2.12 | Frontend: Social posts page (list, generate, edit) | Frontend | 4 days | 2.6 |
| 2.13 | Frontend: Platform post preview components | Frontend | 3 days | 2.12 |
| 2.14 | Frontend: Social calendar page | Frontend | 4 days | 2.10 |
| 2.15 | Frontend: Social analytics dashboard | Frontend | 3 days | 2.9 |
| 2.16 | Frontend: Zustand social store | Frontend | 1 day | 2.11 |
| 2.17 | Notifications integration (publish success/failure) | Backend | 1 day | 2.7 |
| 2.18 | Automation stage 8 integration | Backend | 2 days | 2.7, 1.6 |
### Phase 3: Video Creator — Core (Weeks 6-10)
| # | Task | Type | Effort | Dependencies |
|---|------|------|--------|-------------|
| 3.1 | `GenerateVideoScript` AI function + prompt templates | Backend AI | 3 days | None |
| 3.2 | TTS integration service (OpenAI TTS API) | Backend service | 2 days | None |
| 3.3 | TTS integration service (ElevenLabs — optional) | Backend service | 2 days | ElevenLabs API key |
| 3.4 | Stock video/image fetcher (Pexels + Pixabay) | Backend service | 2 days | API keys |
| 3.5 | Visual asset assembler (collect images, stock, generate missing) | Backend service | 3 days | 3.4, existing ImageGen |
| 3.6 | Video composer service (FFmpeg + MoviePy pipeline) | Backend service | 5 days | 1.7 |
| 3.7 | Subtitle generator (SRT from script timestamps) | Backend utility | 1 day | None |
| 3.8 | Text overlay renderer (Pillow + Pygments for code) | Backend utility | 2 days | None |
| 3.9 | `GenerateVideoSEO` AI function | Backend AI | 1 day | None |
| 3.10 | Thumbnail generator (AI image + text overlay) | Backend service | 2 days | Existing ImageGen |
| 3.11 | VideoProject CRUD ViewSet + serializers | Backend API | 2 days | 1.3 |
| 3.12 | Video rendering Celery tasks (separate queue) | Backend task | 2 days | 3.6 |
| 3.13 | YouTube upload service (YouTube Data API v3) | Backend service | 3 days | YouTube API credentials |
| 3.14 | Instagram Reels upload service | Backend service | 2 days | 2.1 (Facebook OAuth) |
| 3.15 | TikTok video upload service | Backend service | 2 days | TikTok API credentials |
| 3.16 | Frontend: Video projects page (list, create) | Frontend | 3 days | 3.11 |
| 3.17 | Frontend: Script editor page | Frontend | 3 days | 3.1 |
| 3.18 | Frontend: Video timeline/preview page | Frontend | 5 days | 3.6 |
| 3.19 | Frontend: Voice selector component | Frontend | 2 days | 3.2 |
| 3.20 | Frontend: Video analytics page | Frontend | 2 days | 3.13 |
| 3.21 | Frontend: Zustand video store | Frontend | 1 day | 3.16 |
| 3.22 | Notifications integration | Backend | 1 day | 3.12 |
| 3.23 | Automation stage 9 integration | Backend | 2 days | 3.12, 1.6 |
### Phase 4: Self-Hosted GPU (Weeks 10-12) — OPTIONAL
| # | Task | Type | Effort | Dependencies |
|---|------|------|--------|-------------|
| 4.1 | GPU server Docker Compose (vLLM + ComfyUI + Coqui TTS) | DevOps | 3 days | GPU hardware |
| 4.2 | vLLM adapter in ModelRegistry (OpenAI-compatible client) | Backend | 2 days | 4.1 |
| 4.3 | ComfyUI adapter in image generation service | Backend | 2 days | 4.1 |
| 4.4 | Coqui TTS adapter in TTS service | Backend | 1 day | 4.1 |
| 4.5 | Health check + fallback logic in ModelRegistry | Backend | 2 days | 4.2, 4.3, 4.4 |
| 4.6 | GPU provider admin UI (settings, monitoring) | Frontend | 2 days | 4.5 |
| 4.7 | Load testing and optimization | QA | 3 days | All above |
### Phase 5: Polish & Integration (Weeks 12-14)
| # | Task | Type | Effort | Dependencies |
|---|------|------|--------|-------------|
| 5.1 | Module enable/disable (ModuleEnableSettings: `socializer_enabled`, `video_creator_enabled`) | Both | 1 day | All above |
| 5.2 | Dashboard widgets (Social Overview, Video Pipeline) | Frontend | 2 days | Phases 2-3 |
| 5.3 | Unified settings: social + video config in Site Settings | Both | 2 days | Phases 2-3 |
| 5.4 | End-to-end testing (full pipeline: content → social + video → published) | QA | 3 days | All above |
| 5.5 | Credit system testing (all new operations correctly deducted) | QA | 2 days | Phases 2-3 |
| 5.6 | Documentation (update all docs: ARCHITECTURE, MODULES, ENDPOINTS, MODELS) | Docs | 2 days | All above |
| 5.7 | Rate limiting and error handling for all platform APIs | Backend | 2 days | Phases 2-3 |
| 5.8 | Data migration for existing users (create default social calendar slots) | Backend | 1 day | Phase 2 |
### Timeline Summary
| Phase | Duration | Focus |
|-------|----------|-------|
| Phase 1 | Weeks 1-3 | Foundation: models, migrations, infra |
| Phase 2 | Weeks 3-6 | Socializer: OAuth, AI, scheduling, frontend |
| Phase 3 | Weeks 6-10 | Video Creator: script, TTS, compositor, frontend |
| Phase 4 | Weeks 10-12 | Self-hosted GPU (optional) |
| Phase 5 | Weeks 12-14 | Polish, integration, testing, docs |
| **Total** | **14 weeks** | **~70 working days** |
---
## 13. Risk & Dependency Matrix
### External Dependencies
| Dependency | Risk Level | Mitigation |
|-----------|------------|------------|
| **Platform API access** (LinkedIn, Twitter, Meta, TikTok) | 🔴 High | Apply for developer access ASAP (can take 2-4 weeks for approval). Twitter/X API pricing changes are unpredictable. |
| **YouTube Data API** | 🟡 Medium | Well-documented, generous quota (10K units/day). Need Google Cloud project + OAuth consent screen review. |
| **ElevenLabs API** | 🟢 Low | Optional — OpenAI TTS is primary. ElevenLabs is premium add-on. |
| **FFmpeg on server** | 🟢 Low | Well-supported, already common in Docker images. Add to Dockerfile. |
| **S3-compatible storage** | 🟢 Low | Many providers (AWS, DO Spaces, Cloudflare R2). Straightforward setup. |
| **GPU hardware** (self-hosted) | 🟡 Medium | Optional phase. Cloud GPU rental (RunPod, Lambda) as interim. |
### Technical Risks
| Risk | Impact | Probability | Mitigation |
|------|--------|------------|------------|
| Video rendering is slow (minutes per video) | User experience | High | Separate Celery queue, progress tracking, async preview |
| Platform API rate limits | Publishing delays | Medium | Queue system with backoff, respect rate limits, spread over time |
| OAuth token expiration | Silent failures | Medium | Proactive token refresh task, user notification on failure |
| Video file sizes (100MB+) | Storage costs, slow uploads | High | Compression optimization, CDN delivery, tiered render quality |
| TTS quality inconsistency | User satisfaction | Medium | Voice preview before generation, multiple provider options |
| Platform API breaking changes | Feature outages | Medium | Abstract platform SDKs behind interface, monitor changelogs |
### File & Directory Structure (New)
```
backend/igny8_core/
├── modules/
│ ├── socializer/ ← NEW
│ │ ├── __init__.py
│ │ ├── views.py # SocialPostViewSet, SocialAccountViewSet, etc.
│ │ ├── serializers.py
│ │ ├── urls.py
│ │ └── admin.py
│ ├── video/ ← NEW
│ │ ├── __init__.py
│ │ ├── views.py # VideoProjectViewSet, etc.
│ │ ├── serializers.py
│ │ ├── urls.py
│ │ └── admin.py
├── business/
│ ├── socializer/ ← NEW
│ │ ├── __init__.py
│ │ ├── models.py # SocialAccount, SocialPost, SocialPostMetrics, SocialCalendarSlot
│ │ ├── services/
│ │ │ ├── adaptation_service.py # AI content adaptation
│ │ │ ├── publishing_service.py # Platform-specific publishers
│ │ │ ├── oauth_service.py # OAuth2 flows for each platform
│ │ │ ├── metrics_service.py # Fetch engagement metrics
│ │ │ └── calendar_service.py # Scheduling logic
│ │ ├── tasks.py # Celery tasks
│ │ └── platform_adapters/
│ │ ├── base.py # Abstract platform adapter
│ │ ├── linkedin.py
│ │ ├── twitter.py
│ │ ├── facebook.py
│ │ ├── instagram.py
│ │ └── tiktok.py
│ ├── video/ ← NEW
│ │ ├── __init__.py
│ │ ├── models.py # VideoProject, VideoAsset, VideoPublishRecord, VideoMetrics
│ │ ├── services/
│ │ │ ├── script_service.py # AI script generation
│ │ │ ├── tts_service.py # TTS provider abstraction
│ │ │ ├── asset_service.py # Visual asset collection
│ │ │ ├── composer_service.py # FFmpeg/MoviePy video composition
│ │ │ ├── subtitle_service.py # SRT generation
│ │ │ ├── publishing_service.py # YouTube/IG/TikTok upload
│ │ │ └── metrics_service.py # Fetch video metrics
│ │ ├── tasks.py # Celery tasks
│ │ └── platform_adapters/
│ │ ├── base.py
│ │ ├── youtube.py
│ │ ├── instagram.py
│ │ └── tiktok.py
├── ai/functions/
│ ├── social.py ← NEW (AdaptContentForSocial, GenerateHashtags, etc.)
│ ├── video.py ← NEW (GenerateVideoScript, GenerateVideoSEO, etc.)
│ └── tts.py ← NEW (TextToSpeech provider abstraction)
frontend/src/
├── pages/
│ ├── Socializer/ ← NEW
│ │ ├── SocialDashboard.tsx
│ │ ├── SocialAccounts.tsx
│ │ ├── SocialPosts.tsx
│ │ ├── SocialPostDetail.tsx
│ │ ├── SocialCalendar.tsx
│ │ └── SocialAnalytics.tsx
│ ├── Video/ ← NEW
│ │ ├── VideoDashboard.tsx
│ │ ├── VideoProjects.tsx
│ │ ├── VideoCreate.tsx
│ │ ├── VideoProjectDetail.tsx
│ │ ├── VideoEditor.tsx
│ │ └── VideoAnalytics.tsx
├── store/
│ ├── socialStore.ts ← NEW
│ └── videoStore.ts ← NEW
├── api/
│ ├── socializer.api.ts ← NEW
│ └── video.api.ts ← NEW
├── components/
│ ├── socializer/ ← NEW
│ │ ├── SocialPostPreview.tsx
│ │ ├── PlatformSelector.tsx
│ │ └── SocialCalendarWidget.tsx
│ ├── video/ ← NEW
│ │ ├── VideoPlayer.tsx
│ │ ├── VideoTimeline.tsx
│ │ ├── ScriptEditor.tsx
│ │ └── VoiceSelector.tsx
│ └── dashboard/
│ ├── SocialOverviewWidget.tsx ← NEW
│ └── VideoPipelineWidget.tsx ← NEW
```
---
## Appendix A: Python Dependencies (New)
```txt
# requirements.txt additions
# Media/Video
moviepy>=1.0.3
pydub>=0.25.1
Pillow>=10.0.0 # Already present
ffmpeg-python>=0.2.0
# Storage
django-storages[s3]>=1.14
boto3>=1.34
# Social Platform SDKs
python-linkedin-v2>=0.9.0
tweepy>=4.14 # Twitter/X
facebook-sdk>=3.1.0
python-instagram>=1.3.2
tiktok-api>=0.1.0 # Or direct HTTP client
# TTS
openai>=1.0 # Already present (for TTS endpoints)
elevenlabs>=0.2.0 # Optional
# Video
google-api-python-client>=2.0 # YouTube Data API
google-auth-oauthlib>=1.0
# Self-hosted (optional)
# vllm served externally — uses OpenAI-compatible client (already has openai package)
# coqui-tts served externally — HTTP API calls
```
## Appendix B: Environment Variables (New)
```env
# Storage
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx
AWS_STORAGE_BUCKET_NAME=igny8-media
AWS_S3_REGION_NAME=us-east-1
MEDIA_CDN_URL=https://cdn.igny8.com
# Social Platform OAuth Apps (stored in IntegrationProvider, but app-level config)
LINKEDIN_CLIENT_ID=xxx
LINKEDIN_CLIENT_SECRET=xxx
TWITTER_CLIENT_ID=xxx
TWITTER_CLIENT_SECRET=xxx
META_APP_ID=xxx
META_APP_SECRET=xxx
TIKTOK_CLIENT_KEY=xxx
TIKTOK_CLIENT_SECRET=xxx
GOOGLE_CLIENT_ID=xxx
GOOGLE_CLIENT_SECRET=xxx
# Optional: Self-hosted GPU
GPU_SERVER_URL=https://gpu.igny8.internal:8000
GPU_SERVER_AUTH_TOKEN=xxx
# Optional: ElevenLabs
ELEVENLABS_API_KEY=xxx
```
## Appendix C: Docker Compose Additions
```yaml
# docker-compose.app.yml additions
worker-social:
build: ./backend
command: celery -A igny8_core worker -Q social --concurrency=4 -l info
depends_on:
- redis
- db
env_file: ./backend/.env
worker-video:
build:
context: ./backend
dockerfile: Dockerfile.video # Includes FFmpeg
command: celery -A igny8_core worker -Q video_render --concurrency=2 -l info
depends_on:
- redis
- db
env_file: ./backend/.env
volumes:
- video_temp:/tmp/igny8_video # Temp render storage
volumes:
video_temp:
```
```dockerfile
# backend/Dockerfile.video
FROM python:3.11-slim
# Install FFmpeg
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . /app
WORKDIR /app
```