forked from sagnik/Project_Velocity
sayan
8e1ffe0e43
#11 Added the complete ComfyUI engine. Co-authored-by: Sayan Datta <sayan@Sayans-MacBook-Air.local> Reviewed-on: sagnik/Project_Velocity#12
92 lines
6.5 KiB
Markdown
92 lines
6.5 KiB
Markdown
### **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.
|
||
|