Why Social Agent AI?

Managing social media across multiple platforms is time-consuming and repetitive. Social Agent AI solves this by giving you a fully autonomous content pipeline that you own and control:

• AI generates your content — Google Gemini creates platform-optimized posts with the right tone, length, and hashtags
• Publishes everywhere at once — Twitter, Instagram, YouTube, TikTok from a single dashboard
• Learns and improves itself — Weekly strategy optimizer analyzes what works and automatically adjusts your posting strategy
• Runs on your servers — No SaaS fees, no data sharing, no vendor lock-in. Your content, your infrastructure

Whether you're a solo content creator, a digital agency managing multiple brands, or a developer building automation tools — this platform gives you everything out of the box.

Features

Content Generation Pipeline

Multi-Platform Publishing

Each platform adapter handles API authentication, media uploads, rate limiting, and retry logic independently. Adapters are auto-registered based on which API credentials you provide — no configuration needed.

Autonomous Automation

• Cron-based scheduling — each account gets its own posting schedule via cron expressions
• Content mix control — configure ratios for original posts, reposts, and replies (e.g. 80/15/5)
• PostgreSQL job queue — reliable background processing with SELECT FOR UPDATE SKIP LOCKED for concurrent-safe dequeuing, plus automatic recovery of jobs interrupted by a crash
• Plugin system — poll external data sources, transform content, and publish automatically
• Smart retries — transient failures (timeouts, rate limits, 5xx) retry with exponential backoff; permanent ones (bad credentials, rejected content) fail fast with a clear error

Analytics & Self-Improvement

• Automatic tracking — fetches engagement metrics (likes, comments, shares, impressions, reach) every 6 hours
• Daily reports — WhatsApp summary at 23:00 with engagement totals, top posts, and per-account breakdown
• Weekly optimization — every Monday at 02:00, analyzes 7-day performance data and auto-tunes:
  • Posting tone (emotional, informative, urgent, hopeful, friendly)
  • Posting schedule (cron expression)
  • Hashtag strategy

Web Dashboard

A modern, single-page dashboard with dark theme and sidebar navigation:

• Dashboard — Real-time stat cards, platform breakdown, account performance table, recent activity feed
• Projects — Create and manage multiple brands/projects with logo uploads and independent configs
• Accounts — Link social media accounts with platform credentials, assign roles (primary/secondary/backup), define content strategies
• Posts — Browse, filter, generate AI content with tone/type selection, review quality/safety scores and errors, edit, and publish directly
• Twitter OAuth — Built-in 3-legged authentication flow
• Password protection — HTTP Basic Auth for the dashboard and API via DASHBOARD_PASSWORD

The dashboard UI is currently in Turkish. Translations are a great first contribution!

Notifications

• WhatsApp integration via whatsapp-web.js
• Real-time alerts for: content generated, post published, post failed, daily summary reports

Quick Start

Prerequisites

Installation

# Clone the repository
git clone https://github.com/YusufSizmaz/social-agent-ai.git
cd social-agent-ai

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials (see Configuration section)

# Set up database
createdb social_media_bot
npm run db:migrate

# Optional: demo project so you can explore without any social credentials
npm run db:seed

# Start development server (auto-reloads on changes)
npm run dev

The dashboard will be available at http://localhost:3000

Upgrading from 1.0? If you created your database with npm run db:push, just run npm run db:migrate — existing schemas are detected and baselined automatically.

Production Deployment

npm run build
npm start

Docker

The easiest way to get started. Includes PostgreSQL, Chromium (for WhatsApp), and FFmpeg.

# Configure environment
cp .env.example .env
# Set at minimum: GEMINI_API_KEY and DASHBOARD_PASSWORD

# Start all services — migrations run automatically on startup
docker compose up -d

What's included in the Docker setup:

• Multi-stage build, running as a non-root user
• PostgreSQL 16 (Alpine) with health checks, bound to localhost only
• Automatic database migrations on startup
• Chromium for WhatsApp Web.js session
• FFmpeg and fonts for the video pipeline
• Persistent volumes for database, WhatsApp session, generated media and temp files
• Container health check (/api/health) and graceful shutdown

Deploying on a server? Put the app behind HTTPS (Caddy, Nginx, Traefik) and see SECURITY.md.

Configuration

Required

Security

Platform Credentials

Add credentials for each platform you want to publish to. Only configure what you need — the system automatically enables platforms based on available credentials.

Optional

Architecture

Project Structure

src/
├── index.ts                  # Entry point — registers adapters/plugins, starts engine
├── config/
│   ├── constants.ts          # Platform limits, rate limits, enums
│   ├── env.ts                # Zod environment validation
│   └── logger.ts             # Winston logger configuration
├── types/
│   └── index.ts              # TypeScript interfaces (PlatformAdapter, ProjectPlugin, etc.)
├── db/
│   ├── index.ts              # Drizzle ORM connection + migration runner
│   ├── migrate.ts            # `npm run db:migrate` entry point
│   └── schema/
│       └── index.ts          # 6 tables: projects, accounts, posts, postAnalytics, jobQueue, logs
├── core/
│   ├── engine.ts             # Main orchestrator — job processing, cron registration
│   ├── content-service.ts    # Text / video generation + quality gate
│   ├── queue.ts              # PostgreSQL job queue (SKIP LOCKED, backoff, stale job recovery)
│   ├── scheduler.ts          # node-cron wrapper
│   ├── account-scheduler.ts  # Syncs account strategies → cron jobs
│   ├── strategy-optimizer.ts # Weekly auto-optimization (tone, schedule, hashtags)
│   ├── content-mix.ts        # Original / repost / reply selection
│   ├── media.ts              # Resolve local, public and remote media
│   ├── rate-limiter.ts       # Per-platform rate limiting via p-queue
│   ├── retry.ts              # Exponential backoff with jitter
│   ├── errors.ts             # Retryable vs. permanent errors
│   └── safety-guard.ts       # Platform fitting + content safety validation
├── ai/
│   ├── prompt-builder.ts     # Adds platform limits, tone and language to prompts
│   ├── text-generator.ts     # Gemini structured text generation
│   ├── quality-checker.ts    # AI quality scoring
│   ├── image-generator.ts    # Imagen + Pexels fallback
│   ├── tts.ts                # Edge TTS text-to-speech
│   ├── video-generator.ts    # FFmpeg video assembly
│   └── video-orchestrator.ts # Full video pipeline orchestrator
├── platforms/
│   ├── base.ts               # Abstract base adapter (rate limiting + retry)
│   ├── twitter/              # Twitter API v2 + OAuth2 flow
│   ├── instagram/            # Instagram Graph API
│   ├── youtube/              # YouTube Data API v3
│   └── tiktok/               # TikTok Content Posting API
├── plugins/
│   └── catpet/               # Example plugin: animal adoption content
├── analytics/
│   ├── tracker.ts            # Fetch & store engagement metrics
│   └── reporter.ts           # Daily summary report generation
├── notifications/
│   └── whatsapp.ts           # WhatsApp Web.js integration
└── server/
    ├── index.ts              # Express app setup, health check
    ├── middleware.ts         # Basic auth, validation helpers, error handler
    ├── schemas.ts            # zod request schemas
    ├── routes/
    │   ├── dashboard.ts      # Analytics and stats endpoints
    │   ├── projects.ts       # Project CRUD + logo upload
    │   ├── accounts.ts       # Account CRUD with credential sanitization
    │   ├── posts.ts          # Post CRUD, AI generation, publishing
    │   └── twitter-auth.ts   # Twitter OAuth2 flow
    └── views/
        └── index.html        # Single-page dashboard application

Database Schema

┌─────────────┐       ┌─────────────┐       ┌─────────────────┐
│  projects   │       │  accounts   │       │     posts       │
├─────────────┤       ├─────────────┤       ├─────────────────┤
│ id (UUID)   │◄──┐   │ id (UUID)   │◄──┐   │ id (UUID)       │
│ name        │   ├───│ projectId   │   ├───│ projectId       │
│ description │   │   │ platform    │   │   │ accountId       │
│ active      │   │   │ role        │   │   │ platform        │
│ config      │   │   │ username    │   │   │ contentType     │
│ createdAt   │   │   │ credentials │   │   │ text, hashtags  │
│ updatedAt   │   │   │ strategy    │   │   │ mediaUrls       │
└─────────────┘   │   │ active      │   │   │ status, tone    │
                  │   │ lastUsedAt  │   │   │ safetyScore     │
                  │   └─────────────┘   │   │ qualityScore    │
                  │                     │   │ platformPostId  │
                  │                     │   │ publishedAt     │
                  │                     │   └────────┬────────┘
                  │                     │            │
                  │   ┌─────────────┐   │   ┌────────┴────────┐
                  │   │  jobQueue   │   │   │ postAnalytics   │
                  │   ├─────────────┤   │   ├─────────────────┤
                  │   │ id (UUID)   │   │   │ id (UUID)       │
                  │   │ type        │   │   │ postId          │
                  │   │ status      │   │   │ likes, comments │
                  │   │ payload     │   │   │ shares, reach   │
                  │   │ priority    │   │   │ impressions     │
                  │   │ attempts    │   │   │ engagementRate  │
                  │   │ scheduledAt │   │   │ fetchedAt       │
                  │   └─────────────┘   │   └─────────────────┘
                  │                     │
                  │   ┌─────────────┐   │
                  │   │    logs     │   │
                  │   ├─────────────┤   │
                  │   │ id (UUID)   │   │
                  │   │ level       │   │
                  │   │ message     │   │
                  │   │ context     │   │
                  │   │ source      │   │
                  │   └─────────────┘   │
                  │                     │
                  └─────────────────────┘

System Flow

                     ┌──────────────┐
                     │   Plugins    │ ← poll external sources (RSS, databases, APIs)
                     └──────┬───────┘
                            │ ContentRequest
                            ▼
┌──────────┐    ┌───────────────────────┐    ┌──────────────────┐
│ Scheduler│───▶│        Engine         │───▶│    AI Pipeline   │
│ (cron)   │    │                       │    │                  │
│          │    │  PostgreSQL Job Queue  │◀───│  Gemini (text)   │
│ per-     │    │  ┌─────────────────┐  │    │  Imagen (image)  │
│ account  │    │  │ SKIP LOCKED     │  │    │  Edge TTS        │
│ strategy │    │  │ dequeue → run   │  │    │  FFmpeg          │
└──────────┘    │  └─────────────────┘  │    └──────────────────┘
                └───────────┬───────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Twitter  │ │Instagram │ │ YouTube  │  + TikTok
        │ API v2   │ │ Graph API│ │ Data API │
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │             │             │
             └─────────────┼─────────────┘
                           ▼
              ┌────────────────────────┐
              │      Feedback Loop     │
              │                        │
              │  every 6h → Analytics  │ ← fetch engagement metrics
              │  daily    → Reporter   │ ← WhatsApp summary
              │  weekly   → Optimizer  │ ← auto-tune strategies
              └────────────────────────┘

Video Generation Pipeline

User Prompt
    │
    ▼
┌─────────────┐    ┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Gemini    │───▶│  Edge TTS   │───▶│ Imagen/Pexels│───▶│   FFmpeg    │
│  (script)   │    │  (audio)    │    │   (image)    │    │  (assembly) │
└─────────────┘    └─────────────┘    └──────────────┘    └──────┬──────┘
                                                                 │
                                                                 ▼
                                                          Final .mp4 Video

Scheduled Jobs

REST API Reference

All endpoints except /api/health and the Twitter OAuth callback require Basic Auth when DASHBOARD_PASSWORD is set. Request bodies are validated; invalid input returns 400 with an issues array.

curl -u admin:$DASHBOARD_PASSWORD http://localhost:3000/api/posts?status=review

Health

Projects

Accounts

Posts

Dashboard & Analytics

Twitter Authentication

Dashboard and post list endpoints support an optional ?projectId= query parameter for project-scoped filtering.

Account Strategies

Each account can run autonomously with a JSON-defined content strategy:

{
  "active": true,
  "tone": "emotional",
  "contentTypes": ["text", "image"],
  "promptTemplate": "Write a social media post about animal welfare",
  "cronExpression": "0 9,13,18 * * *",
  "contentMix": { "original": 80, "repost": 15, "reply": 5 },
  "hashtags": ["#adopt", "#rescue"],
  "language": "tr"
}

Changes made in the dashboard take effect immediately — no restart needed.

The strategy optimizer runs every Monday at 02:00, analyzes the past 7 days of engagement data, and automatically adjusts tone, cronExpression, and hashtags to improve performance.

Writing Plugins

Plugins let you feed content from any external source into the automation pipeline. Implement the ProjectPlugin interface:

import type { ProjectPlugin, ContentRequest, GeneratedContent } from './types/index.js';

export class MyPlugin implements ProjectPlugin {
  name = 'my-plugin';

  async init(): Promise<void> {
    // Connect to your data source (database, API, RSS feed, etc.)
  }

  async poll(): Promise<ContentRequest[]> {
    // Called every 5 minutes — return new content requests.
    // `projectId` may be a project UUID or its name; an active account for the
    // platform is picked automatically (primary role first).
    return [];
  }

  transform(content: GeneratedContent): GeneratedContent {
    // Optionally modify AI-generated content before publishing
    return content;
  }

  getPrompt(request: ContentRequest): string {
    // Build the AI prompt when the request has no `prompt` of its own
    return 'Your prompt here...';
  }

  async destroy(): Promise<void> {
    // Clean up connections
  }
}

Register your plugin in src/index.ts:

engine.registerPlugin(new MyPlugin());

The engine handles everything else — polling your plugin on schedule, generating content via AI, running safety checks, and publishing to all configured platforms.

See src/plugins/catpet/ for a complete working example that polls an external database for animal adoption and lost pet listings.

Tech Stack

Scripts

Contributing

Contributions are welcome. Whether it's a new platform adapter, a plugin, a bug fix, a dashboard translation or documentation improvement — feel free to open a PR.

git clone https://github.com/<your-username>/social-agent-ai.git
cd social-agent-ai
npm install
cp .env.example .env          # DATABASE_URL and GEMINI_API_KEY at minimum
npm run db:migrate
npm run dev

Before opening a PR, run npm run check. See CONTRIBUTING.md for the project layout, how to add a platform adapter, and the PR checklist.

Ideas for a first contribution: English translation of the dashboard · LinkedIn / Bluesky / Threads adapters · RSS feed plugin · more unit tests.

Responsible Use

Automating social media comes with responsibilities. Respect each platform's terms of service and automation rules, label AI-generated content where required, and don't use this project for spam, fake engagement or impersonation.

License

This project is licensed under the MIT License — see the LICENSE file for details.