AI‑Agent‑for‑X (Twitter) — SaaS Growth Agent

Overview

AI‑Agent‑for‑X is a micro‑SaaS platform that helps individuals and businesses automate and grow their presence on X (formerly Twitter). Built with a production‑grade FastAPI backend and a modern React/Next.js frontend using shadcn/ui components, the system provides AI‑powered content generation, post scheduling, engagement automation and comprehensive analytics. Multi‑tenancy and Stripe‑powered billing allow you to monetise the service with flexible plans and usage limits.

This repository contains the source code for both the backend and the frontend of the application. The project is organised into a modular structure under backend/apps/ to keep domain logic separated and maintainable. A Celery worker and Redis queue handle background tasks such as posting to X, generating content with OpenAI and collecting analytics.

Features

User‑facing

• AI‑generated daily tweets – Generate draft tweets using OpenAI models. Users can choose manual approval or automatic posting.
• Post editing & scheduling – Schedule posts for future publication and edit content before sending.
• Post analytics – View likes, replies and repost counts for each post.
• Theme/hashtag/topic customisation – Specify the topics and hashtags the AI should focus on.
• Saved content feed – Curated content from external APIs for inspiration.
• Toggle auto‑post – Decide whether the system posts automatically or waits for approval.
• Usage metrics – Track posts per day and token usage per account.
• Pro features – Sentiment‑aware replies, smart replies to mentions, auto‑like and auto‑reply based on keywords, poll posting, watchlists for influencers or competitors, trend tracking by location and niche‑specific inspiration feeds.

Admin‑facing

• User management – Ban, upgrade or override user accounts.
• Pricing and plan editor – Configure subscription tiers, pricing and usage limits via Stripe integration.
• Feature toggles – Enable or disable individual features per plan tier.
• Revenue dashboard – View MRR, churn, lifetime value (LTV) and average revenue per user (ARPU) via Stripe data.
• Post log viewer – Inspect logs of posts and actions across all users.
• Retry queue monitor – Monitor the Celery queue for failed tasks and retry them.
• API failure tracking – Track failures when calling OpenAI or X APIs.
• Plan enforcement – Enforce rate limits, token usage and post caps based on plan.
• Manual overrides – Force a post, suspend a user or perform a mass post.
• Global kill switch – Pause all AI activity across the platform.

Stack

• Backend – FastAPI, SQLAlchemy, PostgreSQL, Celery, Redis, Stripe, Python‑JWT
• Frontend – Next.js (React), shadcn/ui, Tailwind CSS
• Containerisation – Docker and docker‑compose for local development

Quick Start

1. Clone the repository

   git clone https://github.com/sree-pm/AI-agent-for-X.git
   cd AI-agent-for-X

2. Create a .env file

   Copy .env.example to .env and fill in the required keys for OpenAI, X (Twitter), Stripe, PostgreSQL and Redis.

3. Start the services

   With Docker installed, spin up the stack using:

   docker-compose up --build

   The backend API will be available at http://localhost:8000/api/v1 and the frontend at http://localhost:3000.

4. Run database migrations

   If you add or modify models, generate and apply migrations using Alembic:

   alembic revision --autogenerate -m "Describe change"
   alembic upgrade head

Directory Structure

AI-agent-for-X/
├── backend/                # FastAPI application
│   ├── main.py             # App entrypoint
│   ├── config.py           # Settings and environment
│   ├── database.py         # SQLAlchemy engine/session
│   ├── celery_app.py       # Celery configuration
│   ├── api/
│   │   └── v1/             # Versioned API routes
│   │       ├── auth.py
│   │       ├── posts.py
│   │       └── dashboard.py
│   ├── core/
│   │   ├── security.py     # JWT utilities
│   │   └── deps.py         # FastAPI dependencies
│   └── apps/
│       ├── users/          # User models, schemas, routers
│       ├── posts/          # Post models, schemas, routers
│       ├── engage/
│       ├── mentions/
│       ├── trends/
│       ├── watchlists/
│       ├── polls/
│       └── admin/
├── frontend/               # Next.js application
│   ├── pages/
│   ├── components/
│   ├── lib/
│   ├── hooks/
│   └── styles/
├── docker-compose.yml
├── Dockerfile
├── .env.example
├── LICENSE
└── README.md

Licensing

This software is proprietary and confidential. Unauthorized copying, redistribution or resale is prohibited. All rights reserved © Infonaut Ltd, 2025.

Contributing

Pull requests are welcome as long as they adhere to the architectural conventions defined in this repository. Before contributing, please open an issue to discuss major changes.