Social media analytics and publishing platform. Track viral content, schedule posts, and get AI-powered insights across Twitter, Instagram, TikTok, and LinkedIn.

Prerequisites: Node.js >= 16, Docker (for local MongoDB).

# 1. Start MongoDB
docker compose -f docker-compose.local.yml up -d

# 2. Backend
cd viralens-backend-mvp
cp .env.example .env        # fill in real keys for features you want to test
npm install
npm run dev                 # http://localhost:5000

# 3. Frontend (new terminal)
cd client
npm install
npm run dev                 # http://localhost:3000

The frontend proxies /api/* and /uploads/* to the backend — see client/vite.config.js. Most keys (Stripe, OpenAI, SendGrid, OAuth) are optional for local dev; the app degrades gracefully when they're absent.

All backend config is via environment variables — see viralens-backend-mvp/.env.example.

See DEPLOY.md for the managed-services path (Vercel + Railway + MongoDB Atlas, ~$5/mo). A self-hosted Docker Compose stack with Caddy for auto-SSL is also included.

client/                     React + Vite frontend
viralens-backend-mvp/       Express + MongoDB API
  src/
    controllers/            Route handlers
    models/                 Mongoose schemas
    routes/                 Express routers
    services/               Business logic (ai, oauth, publishing, metrics)
    middleware/             Auth, validation, error handling
    utils/                  Email, encryption, retry helpers
  tests/                    Jest test suites
docker-compose.yml          Self-hosted stack (Caddy + MongoDB + backend + frontend)
docker-compose.local.yml    Local MongoDB only

Contributions are welcome — from small bug fixes and test additions to new platform integrations and AI features.

Quick start for contributors:

1. Browse good first issues or help wanted for something to work on.
2. Read CONTRIBUTING.md for the dev setup, branching, and PR conventions.
3. Open an issue before starting anything large so we can align on scope.
4. Questions? Start a discussion.

Please follow the Code of Conduct in all interactions.

MIT — see LICENSE.