Project Architecture

MarginX AIContent Engine

Project architecture for analyzing competitor content, generating AI-powered marketing campaigns, and automating social media distribution across major platforms.

Project Status

Architecture Planning

ProgressPhase 1

● Architecture & Planning In Progress

○ Frontend Foundation Not Started

○ Backend Development Not Started

01 — Blueprint

Project Overview

MarginX AI Content Engine is a project to build an end-to-end AI marketing system: ingest competitor content, extract marketing intelligence with Claude, generate original campaigns and videos, publish across platforms, and learn from results.

Status: Planning — this site is the architecture presentation while system design is underway. Download the full blueprint for archive.

What this project will do

✓Ingest competitor marketing content at scale.
✓Analyze every video into structured marketing intelligence.
✓Build a searchable knowledge base of successful marketing patterns.
✓Generate original marketing content inspired by those patterns.
✓Produce videos automatically using Claude and Higgsfield.
✓Automatically prepare captions, thumbnails, and metadata.
✓Schedule and publish content across multiple approved social accounts.
✓Continuously learn from publishing analytics to improve future campaigns.

Primary Goals

Build a scalable competitor content libraryAutomate marketing analysisGenerate original marketing campaignsAutomate video productionAutomate social media publishingCreate a continuous AI learning loop

High-level architecture

  1. 01Competitor Sources
  2. 02Content Ingestion
  3. 03Video Processing
  4. 04AI Analysis
  5. 05Knowledge Base
  6. 06Content Generation
  7. 07Video Rendering
  8. 08Distribution Engine
  9. 09Analytics
  10. 10Learning Loop

02 — Documentation

Pipelines & Architecture Docs

Diagrams fall into different categories depending on the audience. For the MarginX AI Content Engine project, pipeline framing is especially useful.

Diagram taxonomy

Workflow Diagram

Step-by-step process from source to output

Product Managers, Engineers, AI Teams

Process Flow Diagram

Sequence of operations (Input → Processing → Output)

Software engineering & business process docs

System Architecture Diagram

Components and how they communicate

Architects & engineering leads

Data Flow Diagram (DFD)

How data moves through services and stores

Data and AI teams

Pipeline Diagram

Best for AI

AI/ML processing stages end-to-end

AI/ML organizations (OpenAI, Anthropic, Meta-style framing)

BPMN

Formal gateways, events, and swimlanes

Enterprise software & operations

Named pipelines

Workflow 1 — Content Engine

Competitor content → structured marketing knowledge

  1. 01Competitor URL
  2. 02Discover Videos
  3. 03Download
  4. 04Extract Audio
  5. 05Transcribe
  6. 06OCR
  7. 07Scene Detection
  8. 08Claude Analysis
  9. 09Marketing JSON
  10. 10Database
  11. 11Embeddings
  12. 12Knowledge Base

Workflow 2 — Content Generation

Knowledge base → original campaign video

  1. 01Knowledge Base
  2. 02Pattern Search
  3. 03Claude
  4. 04Campaign Script
  5. 05Scene Breakdown
  6. 06Higgsfield
  7. 07Generated Video

Workflow 3 — Distribution

Video → multi-platform publish → analytics

  1. 01Generated Video
  2. 02Caption Generator
  3. 03Platform Variants
  4. 04Scheduler
  5. 05Publishing Queue
  6. 06Social Platforms
  7. 07Analytics

Architecture documentation deliverables

Doc 1

System Architecture Diagram

Shows major services: Web App, FastAPI, Claude, Higgsfield, PostgreSQL, Redis, Storage, and Social APIs.

Doc 2

Content Processing Pipeline

Competitor URL → Download → Transcription → Analysis → Knowledge Base → Script Generation → Higgsfield.

Doc 3

Distribution Pipeline

Video → Captions → Scheduling → Multi-account Publishing → Analytics.

Doc 4

Sequence Diagram

Interactions over time between user, backend, Claude, Higgsfield, database, and publishing services.

03 — Core IP

Claude Marketing Analysis

This is the core of the MarginX AI Content Engine project. Everything before Claude analysis is data collection. Everything after depends on the quality of structured marketing intelligence extracted from each video.

Analysis flow

  1. 01Video
  2. 02Whisper · OCR · Scenes · Metadata
  3. 03Unified Video JSON
  4. 04Claude Specialized Analyzers
  5. 05Master Marketing JSON
  6. 06PostgreSQL + Embeddings
  7. 07Knowledge Base
  8. 08Pattern Mining
  9. 09Campaign Generator

Specialized analyzers

1

Marketing Analyzer

HookOfferCTAAudienceICPValue proposition
2

Story Analyzer

Hook → Problem → Agitate → Solution → Proof → CTA
3

Copywriting Analyzer

Power wordsPersuasionUrgencyCuriosityGuaranteesClaims
4

Editing Analyzer

Scene durationJump cutsB-rollZoomsCaptionsTransitions
5

Visual Analyzer

LightingColorsBackgroundBrandingText placementComposition
6

Sales Psychology Analyzer

AuthorityScarcitySocial proofFear/HopeTrustLoss aversion

Two-stage Claude analysis (recommended)

Per-video analysis

Analyze each video independently into rich structured JSON (marketing, story, editing, visuals, psychology). Store permanently so Claude never re-analyzes the same video.

Cross-video pattern mining

Periodically (e.g. every 100 videos or daily), retrieve stored analyses and ask Claude to find recurring patterns, outliers, and recommendations. Save into a Learning Patterns table.

More scalableEasier to debugCheaper to runReusable knowledge that improves over time

04 — Execution Flow

End-to-End Workflow

Complete data flow showing how the MarginX AI Content Engine project transforms competitor content into high-performing marketing campaigns

STAGE 1

React Dashboard

Users submit competitor content through an intuitive interface

CompetitorsVideosURLsCampaignsAnalytics
STAGE 2

FastAPI Backend

REST APIs orchestrate validation, authentication, and async processing

PostgreSQL
Redis+Celery
S3/MinIO
STAGE 3

Content Ingestion

Download & store content from multiple sources using yt-dlp

Facebook
YouTube
URLs
MP4s
Transcripts
ZIP

→ Stored in S3/MinIO & PostgreSQL

STAGE 4

FFmpeg Processing

Extract media components and technical metadata

Audio
Frames
Metadata
STAGE 5

AI Extraction

Intelligently extract text, scenes, and visual elements

Whisper
OCR
Scenes
STAGE 6

Claude Analysis

Extract comprehensive marketing patterns with Claude AI

Hooks
Audience
Pain Points
Offers
CTAs
Story
Editing
Psychology
STAGE 7A

Knowledge Base

PostgreSQL + pgvector for semantic search

Videos & Transcripts
OCR & Scene Data
Hooks & Offers
Narrative & Styles
STAGE 7B

Embeddings

Semantic vectors for pattern mining

Semantic Vectors
Similarity Search
Topic Clustering
Pattern Retrieval
STAGE 8

Content Generation

Claude generates original content using retrieved winning patterns

Script
Hooks
Offer
CTA
Storyboard
Scene Plan
Shot List
Voice-over
Captions
Thumbnail
STAGE 9

Higgsfield Video Rendering

AI-powered video generation with professional animations and transitions

Renders complete videos with scenes, camera motion, effects, and sound design → Saved to PostgreSQL + Object Storage

STAGE 10

Distribution Engine

Generate platform-specific content and publish to all channels

Facebook
Instagram
LinkedIn
YouTube
TikTok
Captions
Hashtags
Thumbnails
Platform-optimized
Auto-published
Schedule ready
STAGE 11

Analytics Engine

Real-time performance tracking across all platforms

Views
Reach
Watch Time
CTR
Likes
Comments
Shares
Retention
Followers
Growth
STAGE 12 - FEEDBACK LOOP

Self-Learning Engine

Claude analyzes performance data and continuously improves content generation

Best Hooks
Best CTAs
Optimal Length
Editing Style
Caption Style
Posting Times
Top Platforms
Retention
Offers
Timing

Continuous Improvement Loop: Every campaign feeds back into the system, making the next generation smarter

05 — Systems

System Architecture

Microservices architecture with AI orchestration for this project

Frontend Layer

  • • React 19 + TypeScript
  • • Responsive Tailwind CSS UI
  • • Global state with Zustand
  • • Real-time data with TanStack Query

API Layer

  • • Python FastAPI
  • • JWT / OAuth2 Authentication
  • • RESTful API design
  • • Request validation & logging

Data Layer

  • • PostgreSQL + pgvector
  • • Vector embeddings search
  • • S3/MinIO object storage
  • • Redis caching & queues

Processing Pipeline

  • • Video download (yt-dlp)
  • • Video processing (FFmpeg)
  • • Transcription (Whisper)
  • • OCR & frame extraction
  • • Celery async task queue

AI & Publishing

  • • Claude API integration
  • • AI analysis & generation
  • • Higgsfield MCP video generation
  • • Multi-platform distribution
  • • Analytics & feedback loop

06 — Stack

Technology Stack

Frontend

React 19
TypeScript
Tailwind CSS
Zustand
TanStack Query

Backend

Python
FastAPI
SQLAlchemy
Celery
Redis

Database

PostgreSQL
pgvector
S3/MinIO

AI/Video

Claude API
Higgsfield MCP
yt-dlp
FFmpeg
Whisper
PaddleOCR

DevOps

Docker
Nginx
GitHub Actions
Prometheus
Grafana

Integration

JWT/OAuth2
Facebook API
Instagram API
LinkedIn API
TikTok API

07 — Delivery

Roadmap & Milestones

10-phase development plan with objectives, deliverables, and exit milestones.

Features / Scope

  • →User authentication
  • →Dashboard UI
  • →Database schema
  • →Backend API
  • →File storage
  • →Job queue
  • →Docker setup

Deliverables

  • ■Authenticated React dashboard
  • ■FastAPI foundation
  • ■PostgreSQL + Redis + MinIO/S3
  • ■Celery worker baseline
  • ■Dockerized local environment

Milestone: Platform ready for development.

Features / Scope

  • →Add competitor
  • →Facebook page import
  • →Video upload
  • →Transcript upload
  • →Bulk importing
  • →Metadata extraction

Deliverables

  • ■Competitor management
  • ■Downloader service (yt-dlp)
  • ■Storage pipeline

Milestone: Successfully import thousands of videos.

Features / Scope

  • →Audio extraction (FFmpeg)
  • →Whisper transcription
  • →OCR (PaddleOCR)
  • →Scene detection (OpenCV)
  • →Metadata extraction

Deliverables

  • ■Timestamped transcripts
  • ■OCR results
  • ■Scene segmentation

Milestone: Every video converted into structured data.

Features / Scope

  • →Hook / audience / pain points
  • →Offer / CTA / story structure
  • →Emotional flow / editing / visual style
  • →Sales framework / marketing psychology
  • →Specialized multi-analyzer pipeline

Deliverables

  • ■Structured JSON analyses
  • ■Searchable analyses
  • ■Vector embeddings

Milestone: Complete marketing knowledge base.

Features / Scope

  • →Semantic search
  • →Pattern retrieval
  • →Similar video search
  • →Hook library
  • →CTA library
  • →Offer library

Deliverables

  • ■Marketing intelligence engine
  • ■pgvector-backed retrieval

Milestone: Claude can retrieve winning marketing patterns.

Features / Scope

  • →Campaign generator
  • →Script generator
  • →Scene planner
  • →Shot planner
  • →Voice-over script
  • →Caption suggestions

Deliverables

  • ■Original marketing scripts
  • ■Scene breakdowns
  • ■Higgsfield-ready prompts

Milestone: One-click campaign generation.

Features / Scope

  • →Claude → Scene JSON
  • →Higgsfield MCP rendering
  • →Rendering queue
  • →Status tracking

Deliverables

  • ■AI-generated videos
  • ■Render queue + status
  • ■Asset persistence

Milestone: End-to-end video generation.

Features / Scope

  • →Caption / hashtag / thumbnail generation
  • →Platform optimization
  • →Scheduling
  • →Publishing to Facebook, Instagram, TikTok, LinkedIn, YouTube

Deliverables

  • ■Publishing calendar
  • ■Scheduler
  • ■Publishing history

Milestone: One-click multi-platform publishing.

Features / Scope

  • →Views / reach / engagement
  • →Watch time / CTR
  • →Comments / shares / saves
  • →Analytics dashboard

Deliverables

  • ■Analytics dashboard
  • ■Metric storage pipeline

Milestone: Complete reporting platform.

Features / Scope

  • →Published videos → analytics → Claude
  • →Pattern discovery
  • →Knowledge base updates
  • →Better future campaigns

Deliverables

  • ■Continuous optimization engine
  • ■Learning Patterns table

Milestone: Self-improving content generation.

08 — Outcomes

Success & Future

Success Criteria

Technical

  • ✓Import thousands of videos reliably
  • ✓Analyze videos with structured marketing outputs
  • ✓Build a semantic knowledge base
  • ✓Generate original marketing campaigns
  • ✓Produce videos through Higgsfield
  • ✓Publish automatically across supported platforms
  • ✓Track analytics and improve over time

Business

  • →Reduce content production time from days to minutes
  • →Enable high-volume publishing across multiple channels
  • →Build a reusable library of proven marketing patterns
  • →Continuously improve campaign performance using analytics

Future Enhancements

A/B testing engineTrend detectionCompetitor monitoring alertsBrand voice personalizationAI campaign plannerAutomated ad creative generationCRM integrationEmail campaign generationLanding page generationMulti-language content generationAgent-based autonomous marketing workflows

Suggested Folder Structure

apps/
  dashboard/
  api/
  workers/
  mcp/
services/
  downloader/
  transcription/
  ocr/
  scene_detection/
  analysis/
  embeddings/
  generation/
  publishing/
  analytics/
database/
storage/
docker/
infrastructure/