Project_Velocity/.Agent Context/Bibels/The Catalyst_ Brief.md

Part 1: First Principles Page Structure Analysis

If "The Catalyst" is an autonomous digital marketing agency, it cannot look like a standard Facebook Ads Manager spreadsheet. It must feel like an executive command center.

Here is the optimized page architecture for the WebOS:

1. The Studio (Visual AI Engine)

• Purpose: Where your ComfyUI workflows (Wan 2.2 and Qwen-Image 2512) live on the frontend.
• Function: Users input raw property data/images, and the system generates variations of cinematic videos and multi-lingual posters.
• Meta Link: Automatically pushes these assets to the Meta Asset Library via API.

2. Campaign Command (Control Surface)

• Purpose: The strategic deployment center.
• Function: Instead of manually setting up ads, the user defines the "Objective" (e.g., "Sell 3BHKs fast") and "Budget". The Claw Agent uses the Meta Marketing API to execute Ad Campaign Management & Automation, handling ad sets, bulk creation, and dynamic creative rotation using the assets generated in The Studio.

3. Intelligence & ROI (Analytics Dashboard)

• Purpose: Real-time visual justification of marketing spend.
• Function: Uses the Ads Insights API to visualize CPA (Cost Per Acquisition) and ROI. Features a "Live Optimization" log showing what the Claw Agent is doing in real-time (e.g., "Agent paused Ad Set B due to high CPA. Shifted budget to Ad Set A.").

4. The War Room (Market Research & Audiences)

• Purpose: AI-driven competitor and audience strategy.
• Function: Integrates the Ad Library API to spy on competitor ads (e.g., Emaar/Damac) and uses the completed Brave Search integration to track real estate trends. Connects directly to the Audience Management API to build Custom/Lookalike audiences dynamically from the Supabase CRM leads.

5. System & Meta Graph (Settings)

• Purpose: The plumbing.
• Function: Uses the Meta Business API for Client Onboarding, Business Asset Management (linking WhatsApp, Instagram, FB Pages), and Permissions Management.

---

Part 2: Software Requirements Specification (SRS)

A. Tech Stack & State Management

• Frontend (Sayan): Next JS (Latest Version), Tailwind CSS, Framer Motion, Recharts, Zustand (for useMarketingStore).
• Backend (Sayan): Python (FastAPI) utilizing the official facebook-business Python SDK.
• Visual Generation (Sagnik): ComfyUI API mode running locally, utilizing Flux-Schnell/Qwen-Image 2512 (Images) and Wan 2.2 14B/1.3B (Video).
• Autonomous Logic (Sourik/Sayan): PicoClaw/IronClaw agent triggered via FastAPI endpoints to manage bidding and rotation.

B. Core API Mappings (Meta to FastAPI)

Sayan must build these specific Python routes:

• POST /api/catalyst/campaigns/create: Triggers Meta Marketing API to build campaigns in bulk.
• POST /api/catalyst/creative/sync: Uploads ComfyUI outputs (Wan 2.2 mp4s / Qwen pngs) directly to the Meta Asset Manager.
• GET /api/catalyst/insights/realtime: Polls Meta Ads Insights API for click-through rates, CPA, and spend limits.
• POST /api/catalyst/audiences/lookalike: Pushes "Qualified" or "Whale" leads from your CRM (Supabase) into Meta to create High-Net-Worth Lookalike Audiences.

---

Part 3: Scientific Breakdown of Tasks (Sprint Plan)

Here are the actionable tasks for you and Sayan to drop directly into your Taiga board for "The Catalyst" module.

👑 Sagnik’s Tasks (Visual AI & Architecture)

1. Expose ComfyUI Endpoints for Catalyst Integration:
   • Action: Ensure the catalyst_poster_qwen.json (Qwen-Image 2512) and cinematic_wan22_14b.json (Wan 2.2) workflows are exposed via the ComfyUI Asynchronous Queue API.
   • Output: Provide Sayan with the exact JSON payload structures required to trigger these renders programmatically from the WebOS.
2. Define Agentic System Prompts for Dynamic Creative:
   • Action: Write the system prompts for the Claw agent. Instruct the agent on how to prompt Qwen-Image 2512 for A/B testing (e.g., "Generate Image A with English typography, Image B with Arabic typography").

💻 Sayan’s Tasks (Full-Stack & Meta API)

1. Build the Catalyst Zustand Store & Layout (app/src/components/modules/Catalyst.tsx):

   • Action: Create useMarketingStore.ts in Zustand to manage campaigns[], activeAssets[], and adInsights{}.
   • UI Build: Construct the 4-column Bento grid for the Analytics Dashboard using Recharts (similar to the LeadVelocityChart in the Dashboard).

2. Meta Business API - Auth & Settings Interface:

   • Action: Build the Settings & API entry fields using DarkInput and GhostButton components.
   • Backend: Implement the OAuth flow in FastAPI to acquire and securely store the Meta System User Access Token in Supabase.

3. Meta Marketing API - The Integration Engine (backend/api/routes_catalyst.py):

   • Action: Write the Python wrappers for the Meta Ads API.
   • Function 1: Implement Audience Management—write a script that automatically queries the Supabase CRM for leads tagged "Closed/Won" and pushes their hashed emails to Meta to update a Custom Audience.
   • Function 2: Implement Dynamic Creative Rotation—write an endpoint that accepts Sagnik's ComfyUI image/video URLs, uploads them to Meta's Ad Library, and assigns them to an active Ad Set for A/B testing.

4. Design the UI/UX Components:

   • Action: Design the frontend component states for "Asset Generation". Use "Apple/Steve Jobs" aesthetic (glassmorphism, backdrop-blur-xl).
   • Detail: Must include a visual "Generation Queue" that uses latency-hiding (e.g., shimmering loading states that say "Wan 2.2 is rendering cinematic lighting...").

5. Real-Time Optimization Dashboard (WebOS):

   • Action: Create a <LiveOptimizationFeed /> component using Framer Motion (AnimatePresence).
   • Details: It should stream WebSocket updates from the backend showing what the autonomous bot is doing (e.g., "Agent Sourik paused Campaign X due to CPA > $50").

First-Principles Summary for Development

By structuring the Meta API exactly like this, you are not building an Ads Manager. You are building an Autonomous Deployment Engine. Sagnik's models (Wan/Qwen) act as the infinite creative agency, Sayan's React/FastAPI stack acts as the pipes, and Sourik's Claw agent acts as the media buyer turning those pipes on and off based on the real-time Meta Insights data.