# MLazy Engine — AI Video Creation & Publishing Studio (Master Architecture & Engineering Specification)
> **Document Version**: 2.0.0
> **Status**: Comprehensive Technical Specification & ER Blueprint
> **Target Platform**: Chrome Extension (MV3) + Python FastAPI Daemon + PostgreSQL (Supabase) + YouTube Data API v3 + Google Veo Engine
---
## 1. Executive Summary & Vision
**MLazy Engine — AI Video Creation & Publishing Studio** is an end-to-end automated video creation, editing, and publishing platform. It turns high-level topics or channel style inspirations into complete, high-quality YouTube videos using LLM script generation, Google Veo video generation (via our Chrome extension bridge), dynamic video merging (`ffmpeg`), and automated YouTube publishing.
---
## 2. System Architecture & Component Diagram
```text
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ CHROME EXTENSION (MANIFEST V3) │
│ │
│ ┌──────────────────────┐ ┌───────────────────────┐ ┌──────────────────────────────────┐ │
│ │ Google OAuth 2.0 │ │ One-Click Trigger │ │ Interactive Prompt Editor UI │ │
│ │ (Identity API) │ │ (Generate 1 / 3 / 5) │ │ (Pause, Edit, Regenerate Scene) │ │
│ └──────────┬───────────┘ └───────────┬───────────┘ └────────────────┬─────────────────┘ │
│ │ │ │ │
│ ┌──────────┴──────────────────────────┴───────────────────────────────┴─────────────────┐ │
│ │ Background Service Worker & Polling Bridge │ │
│ └─────────────────────────────────────┬─────────────────────────────────────────────────┘ │
└────────────────────────────────────────┼────────────────────────────────────────────────────┘
│ HTTP REST (JSON / Bearer JWT)
▼
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ PYTHON FASTAPI BACKEND DAEMON (PORT 8001) │
│ │
│ ┌──────────────────────┐ ┌───────────────────────┐ ┌──────────────────────────────────┐ │
│ │ JWT Security Guard │ │ LLM Script Engine │ │ Style Clone Profiler │ │
│ │ (Auth Middleware) │ │ (Gemini / GPT / Claude│ │ (Channel Style Injector) │ │
│ └──────────┬───────────┘ └───────────┬───────────┘ └────────────────┬─────────────────┘ │
│ │ │ │ │
│ ┌──────────┴──────────────────────────┴───────────────────────────────┴─────────────────┐ │
│ │ Veo Task Dispatcher, ffmpeg Merger & YouTube Uploader Engine │ │
│ └──────────────┬──────────────────────────────┬──────────────────────────────┬──────────┘ │
└─────────────────┼──────────────────────────────┼──────────────────────────────┼─────────────┘
│ │ │
▼ ▼ ▼
┌───────────────────────────┐ ┌───────────────────────────┐ ┌──────────────────────────────┐
│ PostgreSQL (Supabase) │ │ Google Flow Web Session │ │ YouTube Data API v3 │
│ • Users & JWT Sessions │ │ • Live Bearer Interceptor│ │ • Video Upload & Metadata │
│ • Queue, Stories & Jobs │ │ • Google Veo Video Gen │ │ • Playlist & Channel Sync │
│ • Style Profiles & Logs │ │ • Media ID Registration │ │ • Status Monitoring │
└───────────────────────────┘ └───────────────────────────┘ └──────────────────────────────┘
User Chrome Extension FastAPI Backend Google OAuth API PostgreSQL (Supabase)
│ │ │ │ │
├── 1. Click "Sign in" ────────►│ │ │ │
│ ├── 2. Launch Auth Flow ──────►│ │ │
│ │ (chrome.identity) ├── 3. Redirect / Verify ──►│ │
│ │ │◄── 4. OAuth Token ────────┤ │
│ ├── 5. Send Google Token ─────►│ │ │
│ │ ├── 6. Verify Token ───────►│ │
│ │ │◄── 7. Profile Payload ────┤ │
│ │ ├── 8. Upsert User ────────────────────────────────────►│
│ │ │◄── 9. User Record ────────────────────────────────────┤
│ │ ├── 10. Generate Signed JWT │ │
│ │◄── 11. Return JWT Token ─────┤ │ │
│ │ │ │ │
├── 12. App Screen Unlocked ───►│ │ │ │
│ ├── 13. API Request (Bearer JWT)──────────────────────────►│ │
│ │ ├── 14. Validate JWT Guard ────────────────────────────►│
│ │ │◄── 15. User Authorized ───────────────────────────────┤
User Extension UI FastAPI Backend LLM Service Google Veo (Bridge) ffmpeg YouTube API
│ │ │ │ │ │ │
├── 1. Click Generate ►│ │ │ │ │ │
│ ("1 Video") ├── 2. POST /story ───►│ │ │ │ │
│ │ ├── 3. Prompt Script►│ │ │ │
│ │ │◄── 4. 4 Scenes ───┤ │ │ │
│ │◄── 5. Render Draft ──┤ │ │ │ │
│ │ (Pause Screen) │ │ │ │ │
├── 6. Edit/Approve ──►│ │ │ │ │ │
│ ├── 7. POST /render ──►│ │ │ │ │
│ │ ├── 8. Job Status (Queued) ───────────────┼───────────────────┼─────────────► (DB)
│ │ ├── 9. Dispatch Scene 1 Prompt ──────────►│ │ │
│ │ │◄── 10. Scene 1 MP4 Clip Downloaded ────┤ │ │
│ │ ├── 11. Dispatch Scene 2,3,4 Prompts ────►│ │ │
│ │ │◄── 12. All Clips Ready ────────────────┤ │ │
│ │ ├── 13. Execute Merge Command ──────────────────────────────►│ │
│ │ │◄── 14. Merged final_video.mp4 ────────────────────────────┤ │
│ │ │ │
│ │ │── 15. Check Upload Toggle ─────────────────────────────────────────────────┐
│ │ │ ┌────────────────────────────────────────────────────────────────────────┘
│ │ │ │ [IF TOGGLE == ON]
│ │ │ └────────────────────────────────────────────────────────────────────────┐
│ │ │ ▼
│ │ ├── 16. Upload final_video.mp4 ─────────────────────────────────────────────►│
│ │ │◄── 17. Return YouTube Video URL ───────────────────────────────────────────┤
│ │◄── 18. Job Complete ─┤ │
├── 19. View Video ───►│ (With Link) │ │
User Extension UI FastAPI Backend Vision LLM Engine YouTube API
│ │ │ │ │
├── 1. Click Style Clone ►│ │ │ │
│ (Paste Channel URL) ├── 2. POST /style-clone ─►│ │ │
│ │ ├── 3. Fetch Channel Meta ───────────────────────►│
│ │ │◄── 4. Titles, Descriptions & Thumbnails ──────┤
│ │ ├── 5. Extract Visual Style & Tones ─────►│ │
│ │ │◄── 6. Style DNA Profile Payload ────────┤ │
│ │ ├── 7. Save Style DNA Profile to PostgreSQL (DB) │
│ │◄── 8. Profile Saved ─────┤ │
│ │ ("Zack D Films Style")│ │
│ │ │ │
├── 9. Select Style & ───►│ │ │
│ Generate Video ├── 10. POST /story ──────►│ │
│ │ (with style_dna_id) ├── 11. LLM Prompt + Style DNA Injection ──────┐ │
│ │ │ "Zack D Films Style, dark dramatic,..." │ │
│ │ │◄────────────────────────────────────────────┘ │
┌────────────────────────────────────────────────────────┐
│ USERS │
├────────────────────────────────────────────────────────┤
│ PK id UUID DEFAULT gen_random_uuid│
│ UN google_id VARCHAR(255) │
│ UN email VARCHAR(255) │
│ full_name VARCHAR(255) │
│ avatar_url TEXT │
│ plan VARCHAR(50) DEFAULT 'free' │
│ style_clone_unlocked BOOLEAN DEFAULT FALSE │
│ created_at TIMESTAMPTZ │
└───────────────────────────┬────────────────────────────┘
│ 1
│
│ N
┌───────────────────────────┴────────────────────────────┐
│ TOPIC_QUEUE │
├────────────────────────────────────────────────────────┤
│ PK id UUID DEFAULT gen_random_uuid│
│ FK user_id UUID ──────────────────────┐│
│ topic TEXT ││
│ status VARCHAR(50) ││
│ created_at TIMESTAMPTZ ││
└────────────────────────────────────────────────────────┘│
│
┌─────────────────────────────────────────────────────────┘
│
│ 1
├────────────────────────────────────────────────────────┐
│ STORIES │
├────────────────────────────────────────────────────────┤
│ PK id UUID DEFAULT gen_random_uuid│
│ FK user_id UUID │
│ topic TEXT │
│ title VARCHAR(550) │
│ description TEXT │
│ tags TEXT[] │
│ scenes JSONB │
│ style_profile JSONB │
│ status VARCHAR(50) │
│ created_at TIMESTAMPTZ │
└───────────────────────────┬────────────────────────────┘
│ 1
│
│ N
┌───────────────────────────┴────────────────────────────┐
│ VIDEO_JOBS │
├────────────────────────────────────────────────────────┤
│ PK id UUID DEFAULT gen_random_uuid│
│ FK story_id UUID │
│ FK user_id UUID │
│ status VARCHAR(50) │
│ local_video_path TEXT │
│ duration_seconds FLOAT │
│ error_message TEXT │
│ created_at TIMESTAMPTZ │
│ updated_at TIMESTAMPTZ │
└───────────────────────────┬────────────────────────────┘
│ 1
│
│ 1
┌───────────────────────────┴────────────────────────────┐
│ YOUTUBE_UPLOADS │
├────────────────────────────────────────────────────────┤
│ PK id UUID DEFAULT gen_random_uuid│
│ FK job_id UUID │
│ FK user_id UUID │
│ youtube_video_id VARCHAR(255) │
│ youtube_url TEXT │
│ privacy_status VARCHAR(50) DEFAULT 'public'│
│ status VARCHAR(50) │
│ uploaded_at TIMESTAMPTZ │
└────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────┐
│ STYLE_PROFILES │
├────────────────────────────────────────────────────────┤
│ PK id UUID DEFAULT gen_random_uuid│
│ FK user_id UUID │
│ channel_name VARCHAR(255) │
│ channel_url TEXT │
│ style_dna JSONB │
│ created_at TIMESTAMPTZ │
└────────────────────────────────────────────────────────┘
-- Enable UUID extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-- 1. Users Table
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
google_id VARCHAR(255) UNIQUE NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
full_name VARCHAR(255),
avatar_url TEXT,
plan VARCHAR(50) NOT NULL DEFAULT 'free',
style_clone_unlocked BOOLEAN NOT NULL DEFAULT FALSE,
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- 2. Topic Queue Table
CREATE TABLE topic_queue (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
topic TEXT NOT NULL,
status VARCHAR(50) NOT NULL DEFAULT 'pending',
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- 3. Stories & Scene Scripts Table
CREATE TABLE stories (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
topic TEXT NOT NULL,
title VARCHAR(550) NOT NULL,
description TEXT,
tags TEXT[],
scenes JSONB NOT NULL,
style_profile JSONB,
status VARCHAR(50) NOT NULL DEFAULT 'draft',
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- 4. Video Jobs Table
CREATE TABLE video_jobs (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
story_id UUID NOT NULL REFERENCES stories(id) ON DELETE CASCADE,
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
status VARCHAR(50) NOT NULL DEFAULT 'queued',
local_video_path TEXT,
duration_seconds FLOAT,
error_message TEXT,
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- 5. YouTube Uploads Table
CREATE TABLE youtube_uploads (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
job_id UUID NOT NULL REFERENCES video_jobs(id) ON DELETE CASCADE,
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
youtube_video_id VARCHAR(255),
youtube_url TEXT,
privacy_status VARCHAR(50) NOT NULL DEFAULT 'public',
status VARCHAR(50) NOT NULL DEFAULT 'pending',
uploaded_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- 6. Style Profiles Table (Paid Feature)
CREATE TABLE style_profiles (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
channel_name VARCHAR(255) NOT NULL,
channel_url TEXT NOT NULL,
style_dna JSONB NOT NULL,
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- Performance Indexes
CREATE INDEX idx_users_google_id ON users(google_id);
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_topic_queue_user_status ON topic_queue(user_id, status);
CREATE INDEX idx_stories_user_status ON stories(user_id, status);
CREATE INDEX idx_video_jobs_user_status ON video_jobs(user_id, status);
CREATE INDEX idx_youtube_uploads_job ON youtube_uploads(job_id);
/api/v1/auth)POST /api/v1/auth/google: Accepts Google ID token from Chrome extension. Verifies token, upserts user record in PostgreSQL, returns signed JWT.GET /api/v1/auth/me: Returns current authenticated user profile, tier, and unlocked features./api/v1/stories)POST /api/v1/stories/generate: Accepts topic and optional style_profile_id. Calls LLM to generate 3-4 scene prompts. Returns story draft JSON.PUT /api/v1/stories/{story_id}: Saves user edits to titles, descriptions, or individual scene prompts.POST /api/v1/stories/{story_id}/render: Queues story for Google Veo video generation./api/v1/jobs)GET /api/v1/jobs: Lists past generation jobs, rendering statuses, and local video paths.POST /api/v1/jobs/{job_id}/publish: Manually triggers YouTube upload for a completed video in the library./api/v1/style-clone)POST /api/v1/style-clone/analyze: Requires Pro plan. Takes YouTube channel URL, fetches metadata/thumbnails, runs Vision LLM style profiler, saves style_dna to PostgreSQL.GET /api/v1/style-clone/profiles: Returns saved style profiles for user selection.quota_paused, allowing the user to upload manually or retry the next day without losing the generated video.Document compiled and verified for MLazy Engine project repository.