Reddit Agent

AI-powered campaign manager that turns company positioning, Reddit personas, and SEO-style intents into realistic weekly posting calendars, complete with comment swarms, guardrails, analytics, and automation hooks.

Table of Contents

• Why Reddit Agent?
• Feature Highlights
• System Architecture
• Project Structure
• Tech Stack
• Getting Started
• Environment Variables
• Local Development
• Database & Migrations
• Core Workflows
• Testing
• Troubleshooting & Tips

Why Reddit Agent?

Marketing on Reddit is hard: every subreddit has its own etiquette, astroturfing is banned, and scaling “authentic” voices is painful. Reddit Agent (a.k.a. Reddit Mastermind) solves that by treating Reddit like a channel that deserves the same rigor as paid media or lifecycle – strategy inputs go in, deterministic calendars and analytics come out.

The app lets operators model companies, personas, subreddits, and search-style “query targets”. It then synthesizes natural posts via GPT-4.1, enforces subreddit constraints, plans coordinated replies, and tracks downstream engagement/rankings. A built-in scheduler, webhook engine, and analytics layer make it production friendly from day one.

Feature Highlights

• Multi-company workspace – isolate data per brand with their own personas, subreddit mix, and banned claims.
• Persona + subreddit planners – manage handles, expertise, tone, subreddit rules, frequency caps, and preferred formats.
• AI calendar generation – seeded randomness via seedrandom guarantees reproducible weekly plans, populated by OpenAI or deterministic templates (server/lib/planner.ts, server/lib/content-generator.ts).
• Quality guardrails – evaluator assigns 0-100 scores, highlights diversity problems, CTA issues, or rule conflicts before posts leave the lab.
• Full calendar UX – week grid, kanban, and timeline views plus drag-and-drop ordering (client/src/pages/calendar.tsx + @dnd-kit).
• Comment swarm plans – every post receives coordinated follow-up personas and timestamps.
• Automation hooks – background scheduler (server/lib/scheduler.ts) regenerates future weeks, while /api/scheduler/* endpoints expose manual triggers.
• Rank tracking – lightweight Google SERP checks tie Reddit URLs to organic performance (server/lib/ranking-tracker.ts).
• Analytics Ops Center – persona coverage, subreddit mix, quality trendlines, and engagement data visualized with Recharts (client/src/pages/analytics.tsx).
• Webhooks + logbook – signed HMAC webhooks with retries, failure auto-disable, and searchable logs (server/lib/webhooks.ts).
• Replit Auth ready – plug-and-play OpenID Connect login plus session-backed Express middleware (see server/replit_integrations/auth).

System Architecture

┌───────────────────────┐       HTTPS        ┌────────────────────────────┐
│   React 18 + Vite UI  │◀──────────────────▶│ Express API (server/index) │
│   (client/src)        │   /api/*, SSR dev   │  Routes + auth middleware  │
└─────────▲─────────────┘                    └──────────┬─────────────────┘
          │ TanStack Query                                │
          │                                               │
          │                      ┌────────────────────────▼───────────────┐
          │                      │   Domain services (server/lib/*)       │
          │                      │   • planner/content-generator (AI)     │
          │                      │   • evaluator/analytics/ranking        │
          │                      │   • scheduler/webhooks/reddit API      │
          │                      └────────────────────────┬───────────────┘
          │                                               │
          │                            Drizzle ORM        │
          │                                               ▼
          │                             ┌───────────────────────┐
          └────────────────────────────▶│ PostgreSQL (shared/…) │
                                        └───────────────────────┘
                                         │
                                         │ optional integrations
                                         ▼
                              OpenAI / Reddit / Webhook targets

Shared TypeScript models live in shared/, so both client and server read the same schema, insert types, and enums without duplicating code.

Project Structure

.
├─ client/                 # React UI (pages, components, hooks)
├─ server/                 # Express app, routes, domain services
│  ├─ lib/                 # planner, evaluator, scheduler, analytics, etc.
│  └─ replit_integrations/ # Auth + AI helper glue when running on Replit
├─ shared/                 # Drizzle schema + auth models shared across stack
├─ script/build.ts         # Production build pipeline (esbuild + Vite)
├─ design_guidelines.md    # UI/UX principles followed by the client
└─ replit.md               # Original product brief

Tech Stack

• Frontend: React 18, Vite, TypeScript, TanStack Query, Wouter, Tailwind + shadcn/ui, Radix primitives, @dnd-kit, embla-carousel, framer-motion, Recharts, react-day-picker.
• Backend: Node.js + Express, TypeScript modules, Zod validation, OpenAI SDK, date-fns, custom scheduler, websocket-ready HTTP server.
• Data layer: PostgreSQL, Drizzle ORM/Kit, shared schema exports, connection pooling via pg.
• Auth & sessions: Replit OpenID Connect helpers, express-session, connect-pg-simple.
• Automation & Integrations: Webhook service with signed payloads, Reddit API client (token encryption, post metrics, subreddit validation), Google ranking scraper, comment swarm generation.
• Tooling: Vitest, tsx, Tailwind CLI, esbuild, tsx-based build script, drizzle-kit migrations.

Getting Started

1. Clone + install

   git clone https://github.com/Karan-05/reddit-assignment.git
   cd reddit-assignment
   npm install

2. Create .env

   cp .env.example .env    # create by hand if file doesn’t exist

   Fill in the variables listed below (at minimum DATABASE_URL & SESSION_SECRET). If you do not have OpenAI/Replit keys, the planner will fall back to template content.
3. Provision PostgreSQL

   createdb reddit_agent        # or point DATABASE_URL at any Postgres instance
   npm run db:push              # applies Drizzle schema

4. (Optional) Seed demo data

   npx tsx -e "import('./server/lib/seed.ts').then(m => m.seedSampleData())"

5. Run the stack

   npm run dev

   The dev server boots Express on http://localhost:5000 and proxies Vite for hot-reloading the React app.

Environment Variables

Name	Required	Purpose
DATABASE_URL	✅	PostgreSQL connection string for Drizzle + session store.
SESSION_SECRET	✅	Used for Express sessions and encryption of Reddit secrets.
PORT	➖	Defaults to 5000. Change if deploying behind another proxy.
AI_INTEGRATIONS_OPENAI_API_KEY	➖	GPT-4.1 mini key. Without it, content generation uses deterministic templates.
AI_INTEGRATIONS_OPENAI_BASE_URL	➖	Base URL for the OpenAI-compatible endpoint (Replit AI gateway or api.openai.com).
REPL_ID, ISSUER_URL	➖	Required only when running with Replit Auth. Swap out for your own OIDC provider if self-hosting.
AI_INTEGRATIONS_OPENAI_* (chat/image routes)	➖	Additional keys for optional AI integrations under server/replit_integrations.

Local Development

• npm run dev – starts the Express API, scheduler, and dev-mode Vite server with hot module reload.
• npm run build – builds both server (esbuild via script/build.ts) and client (Vite) into dist/.
• npm start – runs the bundled production server from dist/index.cjs.
• npm run check – type-checks with tsc.
• npm run db:push – applies the current Drizzle schema to the database.

Sample data

server/lib/seed.ts exports seedSampleData() that creates the SlideForge demo (company + personas + subreddits + query targets). Run it once after migrations:

npx tsx -e "import('./server/lib/seed.ts').then(m => m.seedSampleData())"

Scheduler

startScheduler() is invoked automatically when the server boots and checks enabled schedules once per minute. You can also hit:

• POST /api/scheduler/run – run the worker immediately (all companies).
• GET /api/scheduler/status – inspect heartbeat + next run.
• POST /api/companies/:id/schedule – toggle weekly automation or change the day/hour + weeks-ahead offset.

Database & Migrations

• Schema lives in shared/schema.ts. Tables cover companies, personas, subreddits, query targets, calendar weeks/items, Reddit OAuth connections, analytics, ranking tracking, and webhooks/logs.
• Drizzle Kit config is in drizzle.config.ts. Generate new migrations with:

  npx drizzle-kit generate
  npm run db:push

• Session storage shares the same Postgres via connect-pg-simple, so no extra Redis dependency is required.

Core Workflows

1. Company setup

• Create a company, define offerings, ICP, banned claims, and default posts-per-week.
• Add personas (voice, tone, constraints, expertise) and subreddits (rules summary, max weekly posts, preferred formats).
• Capture “query targets” – intents the team cares about ranking/contributing to.

2. Calendar generation (server/lib/planner.ts)

• Generates candidate posts by pairing queries, personas, and subreddits, respecting caps and diversity.
• Pulls AI-generated titles/outlines or deterministic templates.
• Builds day-by-day plan + comment swarms, saves via storage.
• Evaluator assigns quality score, issues, and suggestions.

3. Calendar operations (client)

• Calendar page offers week grid, kanban swimlanes, and timeline. Users can drag posts between days, edit outlines, regenerate weeks, and view rationales/constraints.
• Help + onboarding flows (client/src/components/onboarding/*) guide first-time operators.

4. Automation & tracking

• Scheduler auto-creates future weeks (server/lib/scheduler.ts).
• Ranking tracker monitors Google results for tracked Reddit URLs and persists history (storage.getRankings* routes).
• Analytics aggregates stats for dashboards (server/lib/analytics.ts).
• Webhook service signs payloads so downstream systems (e.g., Slack bots, CRMs) can react to new weeks, approvals, or ranking events.

5. Reddit integrations

• server/lib/reddit.ts stores encrypted Reddit OAuth credentials, validates subreddit rule pages, and fetches live post metrics.
• postTracking rows capture upvotes/comments/status which feed analytics + ranking views.

Testing

• Unit tests live under server/lib/__tests__ and run with Vitest:

  npx vitest

• Use npm run check to catch type regressions.
• Planner tests rely on seeded randomness, so keep seeds stable when extending scenarios.

Troubleshooting & Tips

• Auth outside Replit: Replace the middleware in server/replit_integrations/auth with your identity provider or stub the routes for local-only demos.
• OpenAI limits: If requests fail (rate limits/network), the service logs an error and gracefully falls back to template content so planning can continue.
• Google ranking scraping: Uses plain fetch with a desktop UA; heavy usage may hit captchas. Consider swapping for a paid SERP API in production.
• Webhooks stuck? Inspect /api/companies/:id/webhooks/:webhookId/logs (exposed via UI) to see the signed payload, status, and duration.
• Scheduler spam: startScheduler runs every minute; disable company schedules via PUT /api/companies/:id/schedule or stop the interval in server/lib/scheduler.ts when running tests.

Happy shipping! 🎯