Facebook Writer & Ads
Relevant source files
The following files were used as context for generating this wiki page:
- backend/api/facebook_writer/README.md
- frontend/src/components/FacebookWriter/FacebookWriter.tsx
- frontend/src/components/FacebookWriter/RegisterFacebookActions.tsx
- frontend/src/services/facebookWriterApi.ts
- backend/test/test_facebook_writer.py
- frontend/src/components/FacebookWriter/components/PageAboutHITL.tsx
The Facebook Writer & Ads module is a comprehensive AI-powered system designed to generate, optimize, and analyze a wide variety of Facebook content. It provides specialized tools for creating engaging posts, stories, reels, carousels, and high-converting advertisement copy. Within the ALwrity platform, this module serves as a bridge between high-level content strategy and platform-specific execution, leveraging Google's Gemini AI to ensure linguistic alignment with user personas and platform optimization rules.
The system is architected as a FastAPI-based backend and a React-based frontend. It utilizes a Human-In-The-Loop (HITL) approach, allowing users to provide context, preview AI-generated drafts, and apply real-time edits before finalization.
Sources: backend/api/facebook_writer/README.md:3-23, frontend/src/components/FacebookWriter/FacebookWriter.tsx:112-117
System Architecture
The module follows a modern REST API architecture integrated with a multi-modal AI service manager. The backend manages business logic and AI prompts, while the frontend handles user interaction through a React interface supported by CopilotKit for AI assistance.
Backend Structure
The backend is organized into specialized services for each content type, utilizing Pydantic models for request validation and Google's Gemini AI for structured content generation.
The diagram shows the request flow from the frontend through the backend services to the AI provider.
Sources: backend/api/facebook_writer/README.md:27-46, frontend/src/services/facebookWriterApi.ts:3-5
Core Components
| Component | Description |
|---|---|
| FastAPI Backend | Handles RESTful endpoints, request validation, and service orchestration. |
| Gemini AI Provider | Generates text, creates structured JSON responses, and manages temperature control for various content types. |
| CopilotKit Sidebar | Provides an AI chat interface that can directly trigger generation tools or edit existing drafts. |
| Persona Provider | Injects user-specific linguistic style and platform rules into the AI prompts. |
| HITL Components | Interactive forms (Human-In-The-Loop) that allow users to refine inputs before generation. |
Sources: backend/api/facebook_writer/README.md:126-133, frontend/src/components/FacebookWriter/FacebookWriter.tsx:436-450, frontend/src/components/FacebookWriter/RegisterFacebookActions.tsx:44-55
Content Generation Tools
The system provides 10 specialized tools categorized into creation, business, and marketing functions.
Tool Categories
- Content Creation: Post Generator, Story Generator, Reel Generator, Carousel Generator.
- Business Tools: Event Description Generator, Group Post Generator, Page About Generator.
- Marketing Tools: Ad Copy Generator, Hashtag Generator, Engagement Analyzer.
Sources: backend/api/facebook_writer/README.md:7-23
Workflow: Post Generation
Post generation involves a sequence of user inputs (business type, audience, goals) that are mapped to valid backend enums before being processed by the AI.
The sequence shows the interaction between the user, the frontend interface, and the backend AI services.
Sources: frontend/src/components/FacebookWriter/RegisterFacebookActions.tsx:69-98, frontend/src/components/FacebookWriter/FacebookWriter.tsx:473-490
Ad Copy & Marketing Services
The Ad Copy Generator is a specific marketing tool designed for high conversion. It generates primary text, headlines, and descriptions based on target audience interests and unique selling propositions (USP).
Ad Copy Request Parameters
The adCopyGenerate service requires detailed targeting and budget parameters:
| Parameter | Type | Description |
|---|---|---|
product_service | String | The specific item being advertised. |
ad_objective | String | e.g., "Conversions", "Brand Awareness". |
ad_format | String | e.g., "Single image", "Video". |
targeting_options | Object | Includes age group, location, interests, and behaviors. |
unique_selling_proposition | String | The key differentiator for the product. |
budget_range | String | User-defined budget context for AI recommendations. |
Sources: frontend/src/services/facebookWriterApi.ts:54-80, backend/test/test_facebook_writer.py:112-130
Multi-Variation Output
The system generates multiple variations for ad components, allowing users to choose the best fit:
- Headline Variations: Multiple catchy titles.
- Primary Text Variations: Different narrative approaches for the main ad body.
- CTA Variations: Multiple Call-To-Action options (e.g., "Sign Up", "Learn More").
Sources: frontend/src/components/FacebookWriter/RegisterFacebookActions.tsx:501-510, frontend/src/components/FacebookWriter/FacebookWriter.tsx:684-706
Implementation Logic
Persona Integration
The module uses a PlatformPersonaProvider to inject user-specific writing styles. This ensures that generated Facebook content matches the user's archetype (e.g., "Expert", "Creator") and adheres to platform rules like character limits (63,206 chars) and optimal length (40-80 words).
// Example Persona Data Context used by AI
const personaGuidance = `
- PERSONA: ${corePersona.persona_name}
- LINGUISTIC STYLE: ${corePersona.linguistic_fingerprint?.lexical_features?.go_to_words}
- PLATFORM: Facebook
- OPTIMAL LENGTH: ${platformPersona.content_format_rules?.optimal_length}
`;
Sources: frontend/src/components/FacebookWriter/FacebookWriter.tsx:441-460
Editing & Preview System
The frontend implements a "Diff Preview" system. When a user requests an edit (e.g., "Lengthen" or "Shorten"), the system calculates the change and displays it with color-coded highlighting (green for additions, red for deletions).
The flowchart describes the frontend logic for real-time draft manipulation.
Sources: frontend/src/components/FacebookWriter/FacebookWriter.tsx:48-65, frontend/src/components/FacebookWriter/FacebookWriter.tsx:78-100
Conclusion
The Facebook Writer & Ads module provides a highly structured yet flexible environment for social media marketing. By combining specialized creation tools for Stories and Reels with conversion-focused Ad Copy generators and persona-aware AI, it allows users to maintain a consistent professional voice while optimizing for Facebook's specific engagement patterns.
Sources: backend/api/facebook_writer/README.md:136-150, frontend/src/components/FacebookWriter/FacebookWriter.tsx:441-445