InfluenceX

An open-source KOL (Key Opinion Leader) marketing automation platform. Discover creators on YouTube, TikTok, and Instagram; run outreach pipelines; track campaign ROI — all in one self-hostable app.

One command to try it: docker compose up -d → npm run seed → open http://localhost:8080/InfluenceX → log in as demo@influencex.dev / demo1234

Features

• Multi-platform KOL discovery — YouTube Data API, TikTok, Instagram (via Apify), Twitch
• Smart email discovery — Regex → bio-link services (Linktree, Beacons) → personal website scrape → Hunter.io domain search
• Outreach pipeline — Draft → review → approve → send via Resend, with inbound webhook to capture replies
• ROI dashboard — Conversion funnel, reply/contract/completion rates, effective CPM, cost-per-outcome
• Campaign management — Organize KOLs into campaigns, track contract → content → payment workflow
• Analytics — Feishu sheet sync, GA4 website metrics, daily content stats trending
• Background automation — Scheduled email sends, auto follow-ups, batch KOL discovery, quota-aware YouTube calls
• Multi-user — Admin / Editor / Viewer RBAC, invite flow, i18n (en/zh)
• Production-grade — Rate limiting, CORS whitelist, login lockout, health checks, ETag caching, gzip, CSV export, webhook notifications (Slack / Feishu / Discord)

Architecture

                    ┌──────────────────────────────────┐
                    │         React SPA (Vite)         │
                    │  Pipeline / Campaigns / ROI /    │
                    │  KOL DB / Contacts / Data / ...  │
                    └─────────────┬────────────────────┘
                                  │ /InfluenceX/api/*
                                  ▼
    ┌─────────────────────────────────────────────────────────────┐
    │                  Express app (server/index.js)              │
    │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐ │
    │  │   auth    │  │  rbac     │  │rate-limit │  │  health   │ │
    │  └───────────┘  └───────────┘  └───────────┘  └───────────┘ │
    │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐ │
    │  │  scraper  │  │ discovery │  │mail-agent │  │ scheduler │ │
    │  │ (YT/TT/IG)│  │  (YouTube)│  │  (Resend) │  │(follow-up)│ │
    │  └───────────┘  └───────────┘  └───────────┘  └───────────┘ │
    │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐ │
    │  │job-queue  │  │  cache    │  │   roi     │  │notifications│
    │  │ (retry/   │  │ (TTL/LRU) │  │dashboard  │  │(Slack/Fei/ │ │
    │  │  backoff) │  │           │  │           │  │  Discord)  │ │
    │  └───────────┘  └───────────┘  └───────────┘  └───────────┘ │
    │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐ │
    │  │  openapi  │  │migrations │  │email-tpl  │  │ yt-quota  │ │
    │  └───────────┘  └───────────┘  └───────────┘  └───────────┘ │
    └─────────────────────────┬───────────────────────────────────┘
                              │
      ┌───────────────────────┼───────────────────────────────┐
      ▼                       ▼                               ▼
 ┌──────────┐        ┌──────────────────┐            ┌──────────────┐
 │PostgreSQL│        │ External APIs    │            │  Webhooks    │
 │ or       │        │ • YouTube        │            │ • Resend     │
 │ SQLite   │        │ • Hunter.io      │            │   inbound    │
 │          │        │ • Resend/SMTP    │            │              │
 │          │        │ • GA4 / Feishu   │            │              │
 │          │        │ • Apify (IG/TT)  │            │              │
 └──────────┘        └──────────────────┘            └──────────────┘

Quick start

Docker Compose (fastest)

git clone https://github.com/oratis/influencex.git
cd influencex
cp .env.example .env          # optional: fill in API keys
docker compose up -d
docker compose exec app npm run seed    # sample data

Open http://localhost:8080/InfluenceX and log in as demo@influencex.dev / demo1234.

Manual (local Node)

git clone https://github.com/oratis/influencex.git
cd influencex
npm install
cd client && npm install && cd ..
npm run build
npm run seed       # optional sample data
npm start

Uses SQLite by default — no external DB required.

Configuration

Set environment variables (or copy .env.example to .env):

Variable	Purpose
DATABASE_URL	PostgreSQL connection string (omit to use SQLite)
ADMIN_EMAIL / ADMIN_PASSWORD	Auto-create admin on first boot
YOUTUBE_API_KEY	YouTube Data API v3
RESEND_API_KEY	Email sending
RESEND_FROM_EMAIL / RESEND_REPLY_TO	Sender/reply-to addresses
RESEND_WEBHOOK_SECRET	Svix signing secret for inbound webhook
HUNTER_API_KEY	Hunter.io domain search
APIFY_TOKEN	Instagram/TikTok scraping via Apify
GA4_PROPERTY_ID / GOOGLE_APPLICATION_CREDENTIALS	Website analytics
FEISHU_APP_ID / FEISHU_APP_SECRET	Feishu sheet sync
NOTIFY_SLACK_WEBHOOK_URL	Slack notifications
NOTIFY_FEISHU_WEBHOOK_URL	Feishu bot notifications
NOTIFY_DISCORD_WEBHOOK_URL	Discord notifications
CORS_ORIGINS	Comma-separated list, production only
SCHEDULER_ENABLED	Set false to disable background email scheduler

See .env.example for the full list.

API documentation

Live Swagger UI at http://localhost:8080/InfluenceX/api/docs after starting the server. Raw OpenAPI 3.1 spec at /api/openapi.json.

Deployment

Google Cloud Run

./setup-secrets.sh   # one-time / when rotating: push .env values to GCP Secret Manager + grant IAM
./deploy.sh          # builds, pushes, deploys (mounts secrets via --update-secrets)

Uses Cloud SQL via --add-cloudsql-instances — the app connects over Unix socket when K_SERVICE is set.

Sensitive values (MAILBOX_ENCRYPTION_KEY, RESEND_API_KEY, OAuth client secrets, DB URL, etc) live in GCP Secret Manager and are mounted into the container as env vars at runtime — they never appear in gcloud run services describe output or the service YAML. The full list of what's a secret vs plain config is in setup-secrets.sh (SECRET_NAMES) and deploy.sh (SECRETS_CSV); keep them in sync when adding new secrets.

To rotate a single secret:

printf 'new-value' | gcloud secrets versions add SECRET_NAME --data-file=-
./deploy.sh   # or: gcloud run services update influencex --region us-central1

Any Docker host

docker build -t influencex .
docker run -p 8080:8080 --env-file .env influencex

Tech stack

• Backend: Node.js 20+, Express 5, PostgreSQL 15 or SQLite
• Frontend: React 18, Vite, Recharts (lazy-loaded)
• Email: Resend (with SMTP fallback via nodemailer)
• External: YouTube Data API, Hunter.io, Apify, GA4, Feishu Open Platform
• Tests: Node built-in test runner, GitHub Actions CI

Project status

Seven phases delivered (see CHANGELOG for details):

1. Security — hardcoded-secret removal, CORS whitelist, login lockout, rate limiting
2. UI polish — Toast/ConfirmDialog, 404 page, error-state normalization
3. Core — real email sending, real KOL collection, YouTube quota tracking, DB migrations, email templates
4. Advanced — CSV export, RBAC, webhook notifications, email scheduler
5. Production — 65 unit tests, CI pipeline, rate limiting, health endpoints, ROI backend, code splitting
6. Frontend — ROI dashboard, i18n (en/zh), user management, OpenAPI docs
7. Scale — job queue, TTL cache, Apify integration, Docker Compose, community docs

Contributing

See CONTRIBUTING.md. Bug reports and PRs are welcome.

License

MIT © 2026 InfluenceX Contributors