Skip to content

README.md

Latest commit

 

History

History
118 lines (81 loc) · 2.61 KB

README.md

File metadata and controls

118 lines (81 loc) · 2.61 KB

xtweetly

AI-assisted X growth and monetization platform.

xtweetly helps creators and teams connect multiple X accounts, generate strategy-aware tweet drafts with AI, automate posting flows, and optimize for measurable growth and revenue over time.

Monorepo Structure

Apps

  • apps/web - Vite + React landing/admin frontend
  • apps/api - Fastify API (/api/v1/*) for auth, accounts, preview, posting, and job triggers
  • apps/worker - tweet orchestration worker (run-once) with policy checks and strategy execution

Packages

  • packages/shared - shared types and schemas
  • packages/db - Drizzle + SQLite schema and repositories

Core Product Flow

  1. Connect one or more X accounts.
  2. Configure account-level strategy (static or AI-assisted).
  3. Generate previews and publish/schedule tweets.
  4. Run orchestration (run-once or cron) to execute eligible posts.
  5. Track attempts and iterate toward higher engagement and conversion.

Prerequisites

  • Node.js 20+
  • pnpm 10+

Quick Start

  1. Install dependencies
pnpm install
  1. Configure environment files
cp apps/api/.env.example apps/api/.env
cp apps/worker/.env.example apps/worker/.env
  1. Set required values in .env
  • INTERNAL_API_KEY
  • X_CLIENT_ID
  • X_CLIENT_SECRET
  • X_REDIRECT_URI
  • OPENROUTER_API_KEY
  • SQLITE_PATH (if you want a custom location)
  1. Run apps in development
pnpm --filter @xtweetly/api dev
pnpm --filter @xtweetly/web dev
pnpm --filter @xtweetly/worker dev

Or run the whole monorepo in parallel:

pnpm dev

Build and Typecheck

pnpm build
pnpm typecheck

API Overview

Base path: /api/v1

  • GET /auth/x/start
  • GET /auth/x/callback
  • GET /accounts
  • POST /accounts
  • PATCH /accounts/:username/strategy
  • POST /accounts/:username/preview
  • POST /accounts/:username/tweets
  • POST /jobs/run-once
  • GET /attempts

Protected endpoints require:

Authorization: Bearer <INTERNAL_API_KEY>

Worker Notes

  • Executes orchestrator once per run (run-once)
  • Applies anti-spam controls (daily limit, cooldown, duplicate prevention)
  • Supports static and ai strategies
  • Use cron/systemd with node dist/app/run-once.js for production scheduling

UI and Design Notes

  • Frontend style and system notes: apps/web/DESIGN.md
  • Landing page messaging is focused on account growth + monetization via AI automation

Documentation

  • Architecture overview: docs/architecture.md

Security

  • Never commit .env files or API keys.
  • Rotate INTERNAL_API_KEY and provider keys regularly.
  • Restrict callback URLs and API origins in production.