### **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.