3. Technical Architecture: 7-Phase Production Implementation

3.1 Implementation overview

The Social Media Automation module was built across 7 phases delivered between February 19-20, 2026, with hardening and AG2 integration completed March 4, 2026. The full implementation spans 16 files across blueprints, services, and models, totaling approximately 12,000 lines of production code.

Component	File	Lines	Purpose
API Blueprint	blueprints/features/social_media_api.py	~1,354	All REST endpoints
Orchestrator	services/social_media_service.py	~959	Cross-platform publish dispatch
Content Engine	services/social_content_engine.py	~600	AI caption, image, video, repurpose, plan
Meta Service	services/meta_social_service.py	~636	Facebook Pages + Instagram Business
YouTube Service	services/youtube_social_service.py	~860	YouTube Data API v3, full automation
LinkedIn Service	services/linkedin_social_service.py	~450	OAuth2 3-legged, ugcPosts API
Pinterest Service	services/pinterest_social_service.py	~410	OAuth2 with Basic auth, pin creation
Twitter Service	services/twitter_social_service.py	~395	OAuth2 PKCE, tweet + media upload
TikTok Service	services/tiktok_social_service.py	~400	Content Posting API, video publishing
GBP Service	services/gbp_social_service.py	~430	Google Business Profile posts + reviews
Lead Engine	services/social_lead_engine.py	~800	Rules engine, inbox, lead scoring
Lead Scoring	services/lead_scoring_service.py	~375	5-weight social scoring model
AG2 Toolkit	services/toolkits/social_media_toolkit.py	~441	14 tools, dual decorator pattern
Admin Panel	blueprints/admin/social_media_admin.py	~274	Stats, credit rates, tier capabilities
Frontend	templates/modules/social-media.html	~3,600	11-tab dashboard
Models (7)	social_account.py, social_post.py, social_campaign.py, social_lead_rule.py, social_engagement.py, content_item.py, social_automation.py	~440	7 DB tables

3.2 Platform architecture -- VALIDATED

Platform scope:

PLATFORMS = ['facebook', 'instagram', 'linkedin', 'twitter', 'pinterest', 'tiktok', 'youtube', 'gbp']

Each platform has a dedicated service file with its own OAuth2 implementation, token storage strategy, and API client. This separation prevents platform-specific quirks (token lifetimes, rate limits, media requirements) from leaking across services.

Authentication Storage: All OAuth tokens are Fernet-encrypted at rest via NeuroGen's standard UserExternalApiKey model. Per-service encryption salts prevent a compromise of one token from exposing others. Token refresh logic is handled automatically within each service before expiry.

Platform Connection Summary:

Platform	Auth Method	Token Lifetime	Auto-Refresh	API Version
Facebook / Instagram	OAuth2 via Meta App	60 days (long-lived)	On expiry	Meta Graph API v21.0
LinkedIn	OAuth2 3-legged	60 days	No (re-auth required)	/v2/ugcPosts
Pinterest	OAuth2 + Basic auth	30 days	Yes (365d refresh token)	/v5/pins
X / Twitter	OAuth2 PKCE	Configurable	Yes	Twitter API v2
TikTok	OAuth2	Configurable	Yes	Content Posting API
YouTube	Google OAuth (scope merge)	Google standard	Yes	YouTube Data API v3
Google Business Profile	Google OAuth (scope merge)	Google standard	Yes	GBP API v4.9

The Google services (YouTube and GBP) share the same Google OAuth flow via scope merging in google_auth_service.py, preventing users from needing to authenticate Google twice.

Publish dispatch (social_media_service.py):

The orchestrator's _publish_to_platform() method routes each post to the appropriate service via elif branching based on the platform field. All 8 platforms route through this single dispatch point, so retry logic, credit deduction, and error handling run before any platform-specific code executes.

3.3 AI Content Engine -- VALIDATED

Engine file: services/social_content_engine.py (~600 lines)

The content engine provides 6 AI generation capabilities accessible from the Composer tab:

Caption generation: Routes through quick_ai_chat_sync() with platform-specific system prompts. Facebook captions differ in tone, length, and structure from Twitter tweets or LinkedIn articles. The engine selects the appropriate prompt template based on the target platform(s).

Hashtag generation: Separate quick_ai_chat_sync() call using extracted post context. Returns ranked hashtag sets sized per platform convention (Instagram allows 30, Twitter penalizes excessive tags, LinkedIn prefers 3-5).

Image Generation (Nano Banana / Gemini REST):

# social_content_engine.py - Image generation via Nano Banana
SM_IMAGE_MODEL = os.getenv('SM_IMAGE_MODEL', 'nano-banana-standard')
SM_IMAGE_PRO_MODEL = os.getenv('SM_IMAGE_PRO_MODEL', 'nano-banana-pro')

# Standard: 3 credits | Pro: 12 credits
# Stored to user_storage/{user_id}/social_media/images/{uuid}.png

Video Generation (Google Veo):

SM_VIDEO_MODEL = os.getenv('SM_VIDEO_MODEL', 'veo-standard')
SM_VIDEO_FAST_MODEL = os.getenv('SM_VIDEO_FAST_MODEL', 'veo-fast')

# Fast: 15 credits | Standard: 25 credits
# Stored to user_storage/{user_id}/social_media/videos/{uuid}.mp4

Content repurposing: Accepts a URL, scrapes the content, and uses quick_ai_chat_sync() to generate platform-adapted posts for all 8 platforms simultaneously. A single blog post produces 8 ready-to-schedule variants in one operation. Cost: 5 credits.

Weekly content plan: Generates a 7-day posting schedule with suggested topics, optimal posting times, and draft captions for each platform. Cost: 10 credits.

Code Evidence (credit deduction pattern):

# social_media_api.py - Credits deducted before API call, refunded on failure
def _deduct_credits(user_id, service_key, description):
    rate = get_platform_credit_rate(service_key, SM_CREDIT_DEFAULTS[service_key])
    success = deduct_user_credits(user_id, rate, description)
    if not success:
        raise InsufficientCreditsError(f"Need {rate} credits for {service_key}")
    return rate

# Usage pattern:
deducted = _deduct_credits(current_user.id, 'ai_image', 'Social media image generation')
try:
    result = content_engine.generate_image(prompt)
except Exception:
    refund_user_credits(current_user.id, deducted)  # Atomic refund on failure
    raise

3.4 YouTube Automation -- VALIDATED

YouTube automation is implemented entirely in services/youtube_social_service.py (~860 lines) and is the deepest platform integration in the module. The YouTube service goes beyond posting content — it covers the full channel operations workflow.

Resumable upload:

# youtube_social_service.py - Resumable upload via googleapiclient
from googleapiclient.http import MediaFileUpload

media = MediaFileUpload(
    file_path,
    mimetype='video/*',
    resumable=True,
    chunksize=256 * 1024  # 256KB chunks
)
request = youtube.videos().insert(
    part='snippet,status',
    body=video_metadata,
    media_body=media
)
# Resumes automatically on network interruption
response = None
while response is None:
    status, response = request.next_chunk()

This resumable pattern is necessary for long-form content uploads where network interruptions would otherwise require a complete restart. The service tracks upload progress and can resume from any chunk position.

AI thumbnail generation: After every video upload, the service optionally calls the Nano Banana Pro model to generate a platform-optimized thumbnail (16:9, high contrast, text overlay support) and sets it on the video via videos().update(). Cost: 12 credits.

YouTube Shorts: The service chains Google Veo video generation (15-60 second clip) with automatic vertical aspect ratio handling and direct upload tagged as a Short. The entire Shorts creation flow — from text prompt to published video — is a single API call. Cost: 2 credits (Veo fast model; video generation billed separately).

Daily quota management:

# youtube_social_service.py - Redis-backed quota tracking
YOUTUBE_QUOTA_LIMIT = int(os.getenv('SM_YT_QUOTA_LIMIT', '10000'))

def _check_quota(user_id: str, units_needed: int) -> bool:
    key = f"yt_quota:{user_id}:{date.today().isoformat()}"
    current = int(redis_client.get(key) or 0)
    if current + units_needed > YOUTUBE_QUOTA_LIMIT:
        return False
    redis_client.incrby(key, units_needed)
    redis_client.expire(key, 86400)  # Reset at midnight
    return True

The YouTube Data API v3 enforces a 10,000-unit daily quota per OAuth application. NeuroGen tracks consumption in Redis with a 24-hour TTL and fails gracefully with a quota error rather than letting the Google API return a hard 429.

Tier-gated upload limits:

YOUTUBE_UPLOAD_LIMITS = {
    'demo': 0, 'starter': 5, 'professional': 20, 'business': 100, 'enterprise': -1
}

Analytics caching: Channel and video analytics are cached in Redis with a 1-hour TTL (SM_YT_ANALYTICS_CACHE_TTL), reducing YouTube API quota consumption for users who check analytics frequently.

Full YouTube feature matrix:

Feature	API Method	Credits	Tier Gate
Video upload (resumable)	videos().insert()	3	starter+
AI thumbnail generation	Nano Banana Pro + videos().update()	12	starter+
YouTube Shorts creation	Veo fast + videos().insert()	2 + video	professional+
Comment listing	commentThreads().list()	0	starter+
AI comment reply	comments().insert() + LLM	2	professional+
Channel analytics	channels().list() (cached 1h)	0	starter+
Video analytics	videos().list() (cached 1h)	0	starter+
Playlist listing	playlists().list()	0	starter+
Add video to playlist	playlistItems().insert()	0	starter+

3.5 Engagement Inbox -- VALIDATED

The unified inbox aggregates comments and DMs from Facebook Pages and Instagram Business accounts via Meta Graph API v21.0 and presents them in a single chronological stream with filtering by platform, type, and status.

ThreadPoolExecutor aggregation (social_lead_engine.py):

# social_lead_engine.py - Parallel inbox fetch across all connected accounts
from concurrent.futures import ThreadPoolExecutor

def fetch_unified_inbox(user_id: str, filters: dict) -> list:
    accounts = get_connected_meta_accounts(user_id)
    with ThreadPoolExecutor(max_workers=4) as executor:
        futures = {
            executor.submit(_fetch_account_inbox, account, filters): account
            for account in accounts
        }
        results = []
        for future in as_completed(futures):
            results.extend(future.result())
    return sorted(results, key=lambda x: x['created_time'], reverse=True)

Fetching each account's inbox in parallel prevents a single slow API response from blocking the entire inbox load. Results are merged and sorted by timestamp into a unified timeline.

Redis caching: Inbox results are cached per-user with a 60-second TTL, preventing rapid page refreshes from hitting the Meta API unnecessarily while keeping the inbox fresh enough for real-time monitoring.

AI reply suggestions (Business+ tier): When a user opens an inbox item, the service calls quick_ai_chat_sync() with the comment or DM content and the brand's assistant context to generate a suggested reply. The user can use the suggestion verbatim, edit it, or discard it. Cost: 1 credit (auto-deducted by LLM).

Tier access controls:

Capability	Minimum Tier
Read inbox	starter
Manual reply	professional
AI reply suggestions	business
Bulk actions	business

3.6 Lead Capture Engine -- VALIDATED

Engine file: services/social_lead_engine.py (~800 lines)

The lead capture engine is the most differentiated capability in the module. No standalone social media management platform offers native rules-based lead identification from engagement events — this is typically handled through third-party CRM integrations that operate on a significant delay, if at all.

Trigger types:

# social_lead_rule.py - Lead rule model
class SocialLeadRule(Base):
    __tablename__ = 'social_lead_rules'

    trigger_type = Column(String(50))  # 'keyword', 'engagement_threshold', 'dm_received'
    trigger_value = Column(String(500))  # keyword string or threshold number
    platform = Column(String(50))       # 'facebook', 'instagram', or 'all'
    auto_action = Column(String(50))    # 'reply', 'send_dm', 'create_contact', 'none'
    action_template = Column(Text)      # Template text for automated responses
    is_active = Column(Boolean, default=True)

Three trigger types:

1. Keyword trigger: Fires when a comment or DM contains specified words or phrases. Example: a rule on "how much", "pricing", "cost" creates a CRM contact and sends a DM with pricing information — useful for capturing price inquiries without requiring a human to scan every comment.

2. Engagement threshold: Fires when a user's total engagement count (comments + likes + shares) on a brand's content crosses a configured threshold. A user who has engaged 5+ times is more likely to convert than a one-time commenter. Threshold rules create contacts or flag users for personal outreach.

3. DM received: Fires on any incoming DM. Auto-replies handle initial acknowledgment and information delivery at scale, so no prospect waits hours for a first response.

Lead scoring integration:

When a rule fires and creates a CRM contact, the lead scoring service applies social-specific weights to set an initial score:

# lead_scoring_service.py - Social media scoring weights
SOCIAL_WEIGHTS = {
    'sm_comment':        int(os.getenv('SM_ENGAGE_COMMENT_WEIGHT', '15')),
    'sm_dm':             int(os.getenv('SM_ENGAGE_DM_WEIGHT', '30')),
    'sm_share':          int(os.getenv('SM_ENGAGE_SHARE_WEIGHT', '20')),
    'sm_mention':        int(os.getenv('SM_ENGAGE_MENTION_WEIGHT', '20')),
    'sm_multi_engage':   int(os.getenv('SM_ENGAGE_MULTI_WEIGHT', '10')),
}

A user who sends a DM enters the CRM with a base score of 30 — higher than most email open events — because DM initiation is a stronger buying signal than passive content consumption. All weights are env-configurable, so each deployment can tune scoring for its business context.

CRM integration: The create_contact auto-action calls the Mautic/SuiteCRM integration layer to create a full contact record with source attribution (source: social_media, platform: instagram, trigger: keyword_match). The contact is immediately available in the Communications module for email and SMS follow-up sequences.

Sequence engine integration: social_lead_engine.py triggers the sequence engine's dm channel, which delivers social DMs through the Meta Graph API. A lead captured by a keyword rule on a Facebook comment can be enrolled in an automated follow-up sequence that sends DMs on day 1, day 3, and day 7 — all configured in the Autoresponder tab and executed without human intervention.

---

4. Tier Structure and Credit System

4.1 Tier limits

# social_media_service.py - Tier-gated limits
DEFAULT_TIER_LIMITS = {
    'demo':         {'accounts': 1,  'posts_per_month': 10,   'ai_captions': 5,   'ai_images': 0,   'ai_videos': 0},
    'starter':      {'accounts': 3,  'posts_per_month': 50,   'ai_captions': 30,  'ai_images': 10,  'ai_videos': 0},
    'professional': {'accounts': 8,  'posts_per_month': 200,  'ai_captions': 100, 'ai_images': 50,  'ai_videos': 10},
    'business':     {'accounts': 15, 'posts_per_month': 1000, 'ai_captions': 500, 'ai_images': 200, 'ai_videos': 50},
    'enterprise':   {'accounts': -1, 'posts_per_month': -1,   'ai_captions': -1,  'ai_images': -1,  'ai_videos': -1},
}

For agencies, the tier calculus is straightforward. Business tier at $297/month supports 15 connected accounts and 1,000 posts per month — enough for 15 client accounts posting approximately 67 times per month each, across up to 8 platforms. Enterprise tier removes all caps.

4.2 Credit costs

# social_media_service.py - Credit cost defaults (admin-overridable)
SM_CREDIT_DEFAULTS = {
    'post_text': 1,          # Plain text post, any platform
    'post_media': 2,         # Post with image/video attachment
    'ai_caption': 2,         # AI-generated caption
    'ai_image': 3,           # Standard image generation (Nano Banana)
    'ai_image_pro': 12,      # Pro image generation (Nano Banana Pro)
    'ai_video_fast': 15,     # Fast video generation (Veo fast)
    'ai_video': 25,          # Full video generation (Veo standard)
    'ai_hashtags': 1,        # Hashtag generation
    'ai_repurpose': 5,       # URL-to-multi-platform repurposing
    'ai_plan': 10,           # Weekly content plan generation
    'youtube_upload': 3,     # Video upload
    'youtube_thumbnail': 12, # AI thumbnail generation
    'youtube_short': 2,      # YouTube Shorts creation
    'youtube_ai_reply': 2,   # AI-generated comment reply
    'ai_reply': 1,           # AI reply suggestion in inbox
    'comment_to_dm': 1,      # Convert comment to DM action
}

All 16 credit rates are overridable via PlatformConfig in the admin panel without a code deployment. The 20% global markup applies on top of these rates by default, and is admin-configurable. Rates are cached for 60 seconds.

4.3 Agency economics

For an agency on Business tier ($297/month, 15,000 included credits), running 10 client accounts with moderate AI content usage:

Activity	Volume/month	Credits/unit	Total Credits
Text posts	300	1	300
Media posts	100	2	200
AI captions	200	2	400
AI images (standard)	50	3	150
YouTube uploads	20	3	60
AI thumbnails	20	12	240
Content repurposing	30	5	150
AI inbox replies	100	1	100
Total			1,600 credits

At 1,600 credits against a 15,000 monthly allowance, an agency running 10 active client accounts with heavy AI content assistance uses approximately 11% of their Business tier credit budget on social media. The remaining 89% is available for other modules (email campaigns, AI agents, legal discovery, analytics). Social media automation is not a line item that consumes the entire budget — it is a component within a broader subscription.

---

5. AG2 Toolkit Integration

5.1 Architecture

Toolkit file: services/toolkits/social_media_toolkit.py (~441 lines)

The AG2 toolkit exposes the entire Social Media module as 14 callable tools for autonomous AI agents. The toolkit uses the dual decorator pattern consistent with NeuroGen's other AG2 integrations: both @register_for_llm (for the planner's function schema) and @register_for_execution (for the executor's function map) are applied to each tool.

Registration in ag2_service.py:

# ag2_service.py - _register_tools()
elif tool_type == 'social_media':
    from services.toolkits.social_media_toolkit import register_social_media_tools
    register_social_media_tools(assistant, user_proxy, user_id, session_id)

5.2 Tool Inventory

Tool	Function	Credits
sm_create_post	Create and schedule a post for any platform	1-2
sm_generate_caption	Generate AI caption for given content	2
sm_generate_hashtags	Generate hashtag set for topic + platform	1
sm_generate_image	Generate image from text prompt	3-12
sm_repurpose_content	Repurpose URL to multi-platform posts	5
sm_generate_plan	Generate weekly content plan	10
sm_get_analytics	Retrieve platform analytics summary	0
sm_list_scheduled_posts	List pending scheduled posts	0
sm_cancel_post	Cancel a scheduled post	0
sm_fetch_inbox	Retrieve unified inbox items	0
sm_reply_to_comment	Reply to a comment on any platform	1
sm_send_dm	Send DM on Facebook or Instagram	1
sm_create_campaign	Create a multi-platform campaign	0
sm_upload_youtube	Upload video to YouTube with metadata	3

5.3 SocialPulse Agent Template

NeuroGen ships a pre-configured SocialPulse agent template in agent_templates.py:

• Type: social_media_specialist
• Minimum tier: starter
• Tools: Full 14-tool social media toolkit
• System prompt: NeuroGen 7-Core Principles applied to social media management context
• Default LLM: DEFAULT_LLM_MODEL (Z.AI glm-4.7-flashx by default, overridable)

The SocialPulse template enables a use case no standalone social media tool supports: a business owner describes their content goals in plain language, and the agent generates captions, creates images, schedules posts across all 8 platforms, monitors the inbox, replies to comments, and reports on performance — autonomously, within a single AG2 session.

---

6. Competitive Positioning

6.1 Feature Comparison Matrix

Feature	Hootsuite ($99-739/mo)	Buffer ($15-120/mo)	Sprout Social ($249-499/mo)	Later ($25-80/mo)	NeuroGen ($47-997/mo)
Platforms	8	8	7	7	8
AI caption generation	Limited	Basic	Add-on	No	Full (custom LLM)
AI image generation	No	No	No	No	Yes (Nano Banana)
AI video generation	No	No	No	No	Yes (Google Veo)
Content repurposing	No	No	No	No	Yes (URL → 8 platforms)
Weekly content planning	No	No	No	No	Yes (AI-generated)
Unified inbox	Add-on	No	Yes	No	Yes + AI reply suggestions
Lead capture from engagement	No	No	No	No	Yes (rules engine)
CRM contact creation	No	No	Limited	No	Yes (Mautic + SuiteCRM)
YouTube full automation	Limited	No	Yes	No	Yes (upload, AI thumbs, Shorts)
Ads manager	No	No	Add-on	No	Included (6 platforms)
AG2 agent toolkit	No	No	No	No	14 tools
Per-user pricing	Yes	Yes	Yes ($249/user)	No	No (per-org)
Autonomous agent mode	No	No	No	No	Yes (SocialPulse)
Sequence engine integration	No	No	No	No	Yes (DM channel)

6.2 Key differentiators

Differentiator 1: Integrated AI creation

Hootsuite, Buffer, Sprout Social, and Later are scheduling and analytics tools. None can generate original visual content. NeuroGen's content engine creates images and videos from text prompts within the same session where those assets are scheduled for publishing. The round-trip from "I need a post about our spring sale" to "post scheduled across 8 platforms with AI-generated image, caption, and hashtags" is a single workflow in NeuroGen. In any competitor, it requires at least 3 separate tools.

Differentiator 2: Social-to-pipeline lead capture

The lead capture engine has no equivalent in any of the four comparison platforms. Sprout Social has listening tools that surface mentions, and Hootsuite has a social inbox. Neither converts engagement events into CRM contacts with lead scores and automated follow-up sequences. NeuroGen's lead engine runs in the background, capturing qualified prospects from existing engagement activity and routing them into email/SMS sequences through the Communications module. For agencies running performance-based client engagements, this closes the attribution gap between social activity and measurable pipeline.

Differentiator 3: Autonomous agent execution

The AG2 toolkit means a SocialPulse agent configured once can operate continuously — checking the content calendar, generating missing posts, monitoring the inbox, responding to comments, identifying leads, and reporting performance — without requiring a human to initiate each action. Autonomous social media management has been a marketing category claim for years. NeuroGen's AG2 implementation is backed by production code. None of the four comparison platforms have anything equivalent.

Differentiator 4: Platform breadth without per-seat pricing

Sprout Social's $249/month entry tier is priced per user, not per organization. An agency with a 5-person social team pays $1,245/month before any add-ons. NeuroGen's Business tier at $297/month is per-organization, covers unlimited users within that organization, supports 15 connected accounts, and includes the Ads Manager module (6 platforms), the Communications module, AG2 agents, and every other module on the platform.

Differentiator 5: Depth of YouTube integration

YouTube automation in Sprout Social covers publishing only. NeuroGen's YouTube service covers the full channel operations workflow: upload (resumable), thumbnail (AI-generated), Shorts (AI video + auto-publish), comments (listing + AI replies), analytics (channel + video, cached), and playlists. An agency managing YouTube channels for clients has a complete toolchain within a single NeuroGen subscription.

---

7. Platform Validation Summary

7.1 Compliance Matrix

Capability	Implementation Status	Evidence
8-platform OAuth2 connections	VALIDATED	6 dedicated service files, Fernet-encrypted token storage
AI caption + hashtag generation	VALIDATED	social_content_engine.py via quick_ai_chat_sync()
AI image generation (Nano Banana)	VALIDATED	SM_IMAGE_MODEL env var, 3-credit standard / 12-credit pro
AI video generation (Google Veo)	VALIDATED	SM_VIDEO_MODEL env var, 15-credit fast / 25-credit standard
Content repurposing (URL → 8 platforms)	VALIDATED	content_engine.repurpose_url(), 5 credits
Weekly AI content planning	VALIDATED	content_engine.generate_weekly_plan(), 10 credits
YouTube resumable upload	VALIDATED	MediaFileUpload with 256KB chunks, auto-resume
YouTube AI thumbnail generation	VALIDATED	Nano Banana Pro + videos().update(), 12 credits
YouTube Shorts (Veo + auto-upload)	VALIDATED	youtube_social_service.create_short(), 2 credits
YouTube daily quota tracking	VALIDATED	Redis-backed per-user daily counter with 24h TTL
Unified inbox (FB/IG)	VALIDATED	ThreadPoolExecutor parallel fetch, 60s Redis cache
AI reply suggestions	VALIDATED	quick_ai_chat_sync() in inbox, Business+ tier
Lead rules engine (3 trigger types)	VALIDATED	social_lead_engine.py, SocialLeadRule model
Lead scoring (5 social weights)	VALIDATED	lead_scoring_service.py, env-configurable weights
CRM contact creation from leads	VALIDATED	Mautic + SuiteCRM fire-and-forget hooks
Sequence engine DM channel	VALIDATED	sequence_engine.py dm channel via Meta Graph API
AG2 toolkit (14 tools)	VALIDATED	Dual decorator pattern, wired in _register_tools()
SocialPulse agent template	VALIDATED	agent_templates.py, social_media_specialist type
Admin panel (7 endpoints)	VALIDATED	social_media_admin.py, credit rates + tier capabilities
Rate limiting	VALIDATED	Per-platform rate limit handling, Redis-backed
Health checks	VALIDATED	Periodic token validation, connectivity monitoring
Credit deduction with refund on failure	VALIDATED	_deduct_credits() + refund_user_credits() pattern

7.2 Implementation notes

1. Parallel inbox fetching: ThreadPoolExecutor with 4 workers fetches multiple account inboxes simultaneously. For agencies with 15 connected accounts, this is the difference between a 1-second inbox load and a 15-second one.

2. Environment-configurable credit rates: All 16 credit rates are admin-overridable via PlatformConfig with 60-second cache. Agency operators can set custom pricing per service key without a code deployment.

3. Unified sequence engine integration: The DM channel in the sequence engine is the same sequence engine that handles email steps, SMS steps, and voice broadcast steps — not a separate pipeline. A single automation workflow can send an email on day 1, an SMS on day 2, and a social DM on day 3, managed from one sequence definition.

4. Google OAuth scope merging: YouTube and GBP share the existing Google OAuth flow rather than requiring separate authentication. The scope merging fix in google_auth_service.py (line 217) ensures users are prompted for all required scopes in a single authorization flow.

5. Tier alias compatibility: The TIER_RANK dict includes both old and new tier names (free/demo, entry/starter, pro/professional, premium/business), ensuring no access check fails on legacy account data.

7.3 Production Audit Results (March 4, 2026)

The module hardening pass on March 4, 2026 validated and remediated the following:

Area	Status
Rate limiting on all platform API calls	Implemented
Health check monitoring for connected accounts	Implemented
Token refresh scheduling before expiry	Implemented
IDOR protection on all user-scoped queries	Validated
SSRF protection on URL repurposing input	Validated
Webhook signature verification	Validated
Credit refund on API failure	Validated
Error responses stripped of stack traces	Validated

All features validated as PRODUCTION READY after the March 4 hardening pass.

7.4 Planned improvements

1. TikTok + LinkedIn inbox: The current unified inbox aggregates FB/IG only. TikTok and LinkedIn inbox APIs are available but require additional API approval. Ready to wire once credentials are approved.

2. Pinterest analytics: Pinterest analytics endpoints are structured in pinterest_social_service.py but require a separate Pinterest Analytics API approval from the Ads API. Currently shows post-level data only.

3. Cross-platform performance correlation: The analytics tab currently shows per-platform KPIs independently. A cross-platform view — e.g., "posts with Veo-generated video outperform image posts by X% across all platforms" — would help agencies build performance reports more efficiently.

4. Bulk scheduling from content library: The current workflow schedules one post at a time from the Composer. A bulk scheduling mode that queues multiple content library items across a date range would reduce repetitive work for high-volume accounts.

---

8. Conclusion

NeuroGen's Social Media Automation module addresses three problems that make social media management economically unscalable for agencies: content volume, engagement response latency, and lead capture.

The content volume problem is handled by the AI Content Engine — caption generation, image generation, video generation, URL repurposing, and weekly planning are all callable in the same session where content is scheduled, across all 8 platforms at once. The engagement response problem is handled by the unified inbox with AI reply suggestions and the lead capture engine's auto-action rules, which respond to comments, send DMs, and enroll prospects in follow-up sequences without waiting for a human. The lead capture gap is handled by the rules engine and lead scoring integration, which converts passive social engagement into active CRM pipeline as it happens.

The AG2 toolkit makes all of this autonomous. A SocialPulse agent configured with brand context, content guidelines, and lead rules can manage a client's entire social presence — creating, scheduling, engaging, and reporting — as a continuous background process. This is not scheduled-post automation. It is a running AI system that acts on novel engagement events according to configured rules.

For agencies evaluating social media tooling, the relevant comparison is not NeuroGen versus Hootsuite or Sprout Social in isolation. It is NeuroGen's integrated platform — social, email, SMS, CRM, AI agents, ads management, and analytics under one subscription — versus the stack of 4 to 6 separate tools required to replicate equivalent functionality. Replicating the lead capture engine alone would require a separate CRM integration. Replicating autonomous agent execution would require a product that does not exist in this category. On total cost and functional scope, NeuroGen is the more practical choice for agencies managing social media at scale.

---

References

1. Hootsuite (2025). "Social Media Trends Report." Key finding: 83% of marketers report AI content tools increased output by 3-5x. Agencies managing 10+ client accounts spend average 15 hours/week on content creation.
2. Sprout Social (2024). "The State of Social Media." 54% of marketers cite generating enough content as their top challenge. Engagement rates drop 40% when content is inconsistent across platforms.
3. HubSpot (2024). "State of Marketing Report." Social media is the #1 marketing channel for ROI. Businesses posting 16+ times/month get 3.5x more traffic. AI-assisted content sees 28% higher engagement.
4. Meta Business Platform (2024). "State of Small Business." 72% of small businesses use social media as their primary marketing channel. Average SMB spends 6-12 hours/week managing social media manually.

---

NeuroGen Social Media Automation Module v7.0 -- All 7 phases complete. 8 platforms. 14 AG2 tools. Production ready. NIR-007 generated March 11, 2026.