diwenne/openreply

Purpose and Runtime Shape

OpenReply is a self-hosted Instagram comment-to-DM automation SaaS. It receives official Meta webhooks, matches comments against configured campaigns, queues delivery, and sends private/public replies through Meta APIs. The Next.js application serves dashboard, public pages, OAuth, and HTTP endpoints; a separate BullMQ worker performs durable sending. Entry points: app/api/webhook/route.ts, worker/dm-worker.ts, and app/(dashboard)/layout.tsx.

Web Application and API Boundary

Next.js 16 App Router provides authenticated operational UI plus route handlers. Dashboard pages manage campaigns, automations, inbox, logs, settings, diagnostics, and overview; public pages include shared reports, templates, tracking redirects, and legal/SEO content. Key paths: app/(dashboard)/campaigns/[id]/page.tsx, app/api/dashboard/stats/route.ts, app/r/[slug]/route.ts.

Identity, Workspaces, and Account Connection

Auth.js uses email magic links via Resend. Users operate within role-based workspaces (owner/admin/member), invitations, and one or more connected professional Instagram accounts. Meta OAuth/account lifecycle is isolated behind Instagram API routes and Meta modules. Key paths: app/api/auth/[...nextauth]/route.ts, app/api/instagram/connect/route.ts, lib/auth.ts, lib/workspace-access.ts, lib/meta/oauth.ts.

Campaign Definition and Matching

Campaigns bind Instagram posts/reels to keyword triggers and message behavior: personalized DM text, one or two tracked-link buttons, optional public reply, follow gate, follow-up, and targeting/builder fields. The dashboard builder is the primary authoring interface; shared matching logic determines whole-word or partial keyword hits. Key paths: components/campaign-builder.tsx, app/api/automations/route.ts, lib/utils/keyword-matcher.ts, prisma/schema.prisma.

Event-to-Delivery Flow

Meta calls the webhook endpoint for comment and messaging events. The handler validates/parses events, identifies the Instagram account/workspace and active campaign, filters invalid/self comments, and enqueues matching DM work in Redis. The worker consumes jobs, applies per-account Meta reply limits, performs private reply/public reply/follow-gate interactions, records outcomes, and retries/defers overflow rather than dropping it. Key paths: app/api/webhook/route.ts, lib/meta/webhook.ts, lib/queue/dm-worker.ts, worker/dm-worker.ts.

Persistence, Queueing, and External Services

PostgreSQL is the system of record through Prisma for users, workspaces, accounts, campaigns, event/send logs, tracked links, reports, and follower history. Redis supports BullMQ delivery and likely cache/import coordination. External boundaries are Meta’s Instagram Login/Graph APIs and webhooks, plus Resend authentication email. Deployments separate web hosting from long-running worker hosting; local infrastructure is defined in docker-compose.yml. Key paths: lib/db/client.ts, lib/queue/client.ts, lib/meta/client.ts, docker-compose.yml.

Reporting, Tracking, and Operations

Tracked links route through a server redirect that records clicks; reporting aggregates campaign/link performance and can expose shareable reports. Scheduled endpoints refresh tokens, attach next-reel targets, and snapshot followers; reconciliation recovers comment-processing gaps. Diagnostics and health endpoints expose operational status, including worker health. Key paths: lib/tracking/server.ts, lib/reports/data.ts, app/api/cron/refresh-tokens/route.ts, lib/polling/comment-reconciler.ts, app/api/admin/diagnostics/route.ts.