# MLazy Studio — Notion Master Specification & System Playbook ⚡️

> **Document Version**: 3.0.0  
> **Target Audience**: Product Lead, System Architects & Notion Workspace  
> **Core Stack**: FastAPI Daemon + Chrome Extension (MV3) + Supabase PostgreSQL + Google Veo Bridge + YouTube Data API v3

---

## 🤖 1. WHAT IS IT?

**MLazy Studio** is an automated AI video creation, editing, style cloning, and YouTube publishing platform.

It bridges browser-based AI video generation (Google Veo on Google Flow) with an asynchronous local Python backend server, allowing creators to generate end-to-end videos from a single prompt or YouTube channel inspiration URL.

### Key Capabilities:
- 🎬 **1-Click AI Scripting & Veo Scene Prompting**: Automated Gemini 2.0/1.5 script writing with Pydantic JSON validation.
- 🧬 **Channel Style DNA Cloning**: Scrapes channel metadata and extracts visual lighting, camera angles, narrative tone, and prompt suffixes.
- 🔑 **Native Google OAuth 2.0 Auth**: Chrome extension authentication with live profile avatar rendering and JWT session management.
- 🎞️ **Zero-Loss FFmpeg Merger**: Stitches individual Veo video scenes and multiplexes audio without quality degradation.
- 🚀 **Resumable 5MB YouTube Publisher**: Resumable 5MB chunked YouTube Data API v3 uploader.
- 💳 **Stripe Pro Entitlements**: Webhook-driven creator tier management (`Free` vs `Pro`).

---

## 🏰 2. ER DIAGRAM (DATABASE SCHEMA)

```mermaid
erDiagram
    USERS ||--o{ TOPIC_QUEUE : "has queued topics"
    USERS ||--o{ STORIES : "creates scripts"
    USERS ||--o{ VIDEO_JOBS : "owns rendering jobs"
    USERS ||--o{ YOUTUBE_UPLOADS : "manages uploads"
    USERS ||--o{ STYLE_PROFILES : "saves channel styles"

    STORIES ||--o{ VIDEO_JOBS : "triggers render"
    VIDEO_JOBS ||--|| YOUTUBE_UPLOADS : "publishes to"

    USERS {
        string id PK
        string google_id UK
        string email UK
        string full_name
        string avatar_url
        string plan "free | pro"
        boolean style_clone_unlocked
        datetime created_at
    }

    TOPIC_QUEUE {
        string id PK
        string user_id FK
        string topic
        string status "pending | processing | completed"
        datetime created_at
    }

    STORIES {
        string id PK
        string user_id FK
        string topic
        string title
        string description
        json tags
        json scenes
        json style_profile
        string status "draft | approved | rendering | completed"
        datetime created_at
    }

    VIDEO_JOBS {
        string id PK
        string story_id FK
        string user_id FK
        string status "queued | rendering | merging | completed | failed"
        string local_video_path
        float duration_seconds
        string error_message
        datetime created_at
        datetime updated_at
    }

    YOUTUBE_UPLOADS {
        string id PK
        string job_id FK
        string user_id FK
        string youtube_video_id
        string youtube_url
        string privacy_status "public | private | unlisted"
        string status "pending | uploading | published | failed"
        datetime uploaded_at
    }

    STYLE_PROFILES {
        string id PK
        string user_id FK
        string channel_name
        string channel_url
        json style_dna
        datetime created_at
    }

⏳ 3. ARCHITECTURE & WORKFLOW DEEP-DIVE

A. The Chrome Extension Bridge Workflow (Google Veo Interceptor)

┌─────────────────────────┐      OAuth 2.0       ┌───────────────────────────┐
│ Chrome Extension Popup  ├─────────────────────►│ Google Account Auth       │
└───────────┬─────────────┘                      └─────────────┬─────────────┘
            │                                                  │
            │ Reads JWT & User Profile                         │ User Avatar & JWT
            ▼                                                  ▼
┌─────────────────────────┐      HTTP POST       ┌───────────────────────────┐
│  Google Flow Active Tab ├─────────────────────►│ FastAPI Engine Daemon     │
│ (Injected Script Sniffer)│  Scene Generation   │ (Port 8000 / PostgreSQL)  │
└─────────────────────────┘                      └─────────────┬─────────────┘
                                                               │
                                                 FFmpeg Stitch & YouTube Publish
                                                               │
                                                               ▼
                                                 ┌───────────────────────────┐
                                                 │ YouTube Data API v3       │
                                                 └───────────────────────────┘

1. Token Sniffing: injected.js intercepts authorization headers (Bearer <token>) from active labs.google/fx/tools/flow browser sessions.
2. Scene Execution: Prompts are dispatched sequentially into Google Veo's generation pipeline.
3. Media Download: Generated .mp4 scene files are fetched into local storage (output/).
4. Stream Copies: merger.py executes zero-loss FFmpeg stream copying:

   ffmpeg -f concat -safe 0 -i file_list.txt -c copy output.mp4
   

⚡ 4. SUPERPOWERS & DEEP FEATURES

Superpower #1: Channel Style Cloning Engine

• Extracts 4 core visual attributes from any channel URL:
  1. Tone: Narrative mood (e.g., suspenseful, educational, dramatic).
  2. Visual Style: Lighting, camera distance, 3D model render style.
  3. Prompt Suffix: Automatic prompt append string (e.g., , 3D animation style, dark dramatic lighting, 4k).
  4. Pacing: Preferred clip duration (4s, 6s, or 8s).

Superpower #2: Model Context Protocol (MCP) Integration

• Exposes mlazy-agent commands directly to IDE AI agents (like Claude Desktop, Antigravity IDE, Cursor).
• Tools exposed: generate_script_tool, merge_videos_tool, publish_youtube_tool, clone_style_tool.

Superpower #3: Resumable YouTube Chunked Publisher

• Handles large video uploads reliably using HTTP 308 Resume protocols with 5MB chunks.
• Retries transient network failures automatically without restarting from byte 0.

♟️ 5. OPERATIONAL CHECKLIST & DEPLOYMENT VERIFICATION

Pre-Flight Launch Checklist:

• [x] FastAPI Backend: PYTHONPATH=. uvicorn mlazy_engine.api:app --port 8000 starts cleanly.
• [x] PostgreSQL Database: Supabase connection pool active with SQLite fallback enabled.
• [x] Unit Test Integrity: PYTHONPATH=. pytest mlazy_engine/tests/ passes 15/15 tests.
• [x] Chrome Extension: Manifest V3 mlazy-extension loaded with active Google OAuth Client ID.
• [x] Google OAuth 2.0: Redirect URI https://<EXTENSION-ID>.chromiumapp.org/ registered in Google Cloud Console.
• [x] FFmpeg Binary: ffmpeg installed and verified by get_ffmpeg_binary().
• [x] Stripe Entitlements: Webhook secret configured for checkout.session.completed events.
• [x] GitHub Hygiene: .vscode/, .venv/, and .env added to .gitignore.

Compiled and formatted for import into Notion Workspace.