ModFlow - Moderation Control Room for Reddit
Inspiration
Reddit moderators manage communities through a fragmented set of tools: Modmail, mod log, report queues, post actions, and team communication all live in separate surfaces with no shared state. Threads get handled twice because nobody knows who claimed what. Reports pile up on posts that were already reviewed. New moderators have no context on recurring cases. And the only way to coordinate is to @ each other in Discord.
We built ModFlow because we saw hundreds of frustrated posts on r/ModSupport and r/bugs asking for basic operational features: ownership visibility, routing automation, triage support, and a unified activity trail. None of those exist natively. ModFlow fills that gap.
What it does
ModFlow is a Devvit Web application that turns a Reddit custom post into a live moderation operations center. Everything runs natively inside Reddit through Devvit's serverless platform, Redis state, and the Reddit moderator API.
Here's everything ModFlow brings to a moderation team:
🎯 Command Center (Overview)
The Overview is the moderator's cockpit. It does the thinking so the moderator can act:
- Priority Scoring Engine: Scores every active Modmail conversation by combining claim status, unread count, user replies awaiting response, highlight state, and recency. The single highest-priority thread is always visible.
- Active Claim Card: Shows the moderator's own claimed thread with quick resume and release actions.
- Follow-Up Queue: Surfaces due and overdue follow-ups with one-click claim, open, clear, and handoff actions.
- Pending Handoffs: Shows ownership transfers waiting for acceptance so bottlenecks are visible before pulling more work.
- Shield Hotspot: Highlights the shielded post receiving the most intercepted reports.
- Metric Links: Every stat card navigates directly into its relevant workflow tab.
- One-Click Triage: "Claim + brief" claims the priority thread, generates an AI brief, and opens the workspace in a single action.
🔒 Modmail Workspace with Claims
Reddit Modmail has no native ownership concept. ModFlow fixes this:
- Claim System: Any moderator can claim a conversation. Teammates instantly see who is handling what.
- Assignee Sync: Claiming a thread automatically sets the workspace assignee; releasing clears it only if it still belongs to that moderator.
- Internal Notes: When enabled, ModFlow writes a visible internal Modmail note on claim, making the ownership record portable and auditable inside Reddit itself.
- Conflict Prevention: If a thread is already claimed, the server returns a 409 with the claim owner so the moderator knows immediately.
- Conversation Presence: See who else is currently viewing the same thread in realtime.
📋 Case Management
Every Modmail thread becomes a structured case record without leaving Reddit:
- Assignee & Tags: Categorize and route threads with custom metadata.
- Workspace Status: Track case lifecycle (open, pending, escalated, resolved, etc.).
- Structured Handoffs: Transfer ownership to a specific moderator with a reason and summary. The target accepts to take over the case.
- Scheduled Follow-Ups: Set a deadline. The Overview queue surfaces it when due or overdue.
- Decision Memory: Save the outcome and reasoning for future reference. The AI assistant uses stored precedents to inform briefs on similar cases.
- Saved Reply Templates: Manage reusable response templates and apply them from the composer.
- Quote Support: Quote any message as a Markdown blockquote into the reply composer.
🤖 AI-Assisted Triage
ModFlow provides intelligent moderation support at both the thread and queue level:
- Thread Briefs: For any selected conversation: summary, suggested tone, next steps, draft reply, and a safety note reminding the moderator to verify before sending.
- Bulk Briefs: Generate briefs for multiple threads at once from the Modmail queue.
- Queue Triage Plan: A backlog analysis that explains where pressure is coming from, what should be handled first, and which threads need immediate attention.
- Workflow Spam Evaluation: AI evaluates message content for spam risk (low/medium/high) so automation rules can route suspicious threads before a moderator reads them.
- Decision Precedents: The assistant references saved case decisions to provide context-aware recommendations.
- Graceful Degradation: When no API key is configured, every AI feature falls back to a local rules-based engine (keyword heuristics, URL density scoring, pattern matching). The app is fully functional without external AI.
⚙️ Workflow Automation
The visual Workflow Builder turns moderation policies into executable rules without writing code:
Triggers:
- User sends a message
- Moderator sends a reply or note
- Thread is claimed
- Thread is archived
Conditions (combinable with AND logic):
- Thread state (new, in progress, archived)
- Thread kind (user-to-mod, mod discussion, internal)
- Subject contains pattern
- Tags match
- Workspace status equals
- Assignee is set / unset / equals specific moderator
- Handoff is pending / not pending
- Follow-up is due / not due
- AI spam risk is low / medium / high (evaluated live per message)
Actions (multiple per rule):
- Assign or clear assignee
- Add tags
- Set workspace status
- Create or clear handoff
- Schedule or clear follow-up
- Highlight conversation
- Archive thread
Ownership Automation Settings:
- Auto-assign on first moderator reply when thread is unassigned
- Auto-clear assignee when thread is archived
Formal Verification: The workflow engine is covered by a 23-test simulation suite that validates matching, normalization, and execution without any Reddit dependency.
🛡️ Post Shield
Post Shield solves the "already reviewed" problem. Posts that moderators already approved keep landing back in the queue because users keep reporting them. ModFlow intercepts those reports:
- Shield/Unshield from Post Menu: One-click protection directly from the Reddit post context menu.
- Report Interception: When a report arrives on a shielded post, ModFlow logs the reason and increments a counter instead of flooding the queue.
- Auto-Approve Mode: Optionally re-approves the post automatically after each intercepted report.
- Edit Detection: If a shielded post is edited, the shield clears automatically so modified content gets fresh review.
- Dashboard Tracking: All shielded posts are visible in a dedicated tab with report counts and reason breakdowns.
- Activity Integration: Every intercepted report and shield change appears in the Activity Feed.
📊 Activity Feed & Realtime
One shared operational trail replaces scattered mod logs and Discord pings:
- Event Types: Claims, releases, AI briefs, workflow automation, shield activity, follow-up reminders, mod actions, post reports, app installs, and upgrades.
- Actor Attribution: Every event shows who did what and when.
- Realtime Refresh: Devvit Realtime channels push updates instantly to all open dashboards.
- Conversation Presence: See which moderators are currently viewing the same Modmail thread.
How we built it
| Layer | Technology |
|---|---|
| Frontend | React 19, TypeScript, Tailwind CSS 4, Vite |
| Backend | Devvit Web serverless (Hono router) |
| State | Devvit Redis |
| Realtime | Devvit Realtime channels |
| Reddit API | Modmail, mod actions, post approvals, reports (moderator scope) |
| AI | OpenAI chat completions (optional), local heuristic fallbacks |
| Testing | Node.js native test runner with formal workflow simulation suite |
| Automation | Pure workflow engine with normalization and validation layers |
The architecture is split into three clear concerns:
src/client: React frontend rendered in Devvit Web iframes. A lightweight splash screen for the feed view and a full expanded workspace for the control room.src/server: Hono-based backend with routes for API, menu actions, forms, triggers, and scheduled tasks. Core modules handle Redis state, workflow execution, AI assistance, and normalization.src/shared: Type definitions and contracts shared between client and server for end-to-end type safety.
Challenges we ran into
- No native Modmail UI surface in Devvit. We had to build the entire Modmail experience inside a custom post webview, fetching conversations through the Reddit API and reconstructing the inbox/detail UX from scratch.
- Claim coordination without a database. Redis is key-value only; we built claim ownership, expiration cleanup, assignee sync, and conflict resolution on top of it.
- AI fallback parity. We wanted workflows to work identically whether or not an API key is present. The local spam heuristic uses URL density, keyword group matching, and weighted scoring to approximate the OpenAI evaluation.
- Workflow engine correctness. Rule matching logic, condition evaluation, and action sequencing needed to be provably correct. We built a formal simulation test suite (23 tests) that runs without Reddit, hitting the pure engine with structured inputs and asserting exact outputs.
- Dark mode inside Devvit. The webview cannot read Reddit's theme from CSS directly. We detect the color scheme at runtime, toggle a class, and use CSS variable tokens to switch the entire palette.
- Realtime without WebSockets. Devvit Realtime uses channel-based pub/sub. We had to design the refresh protocol so concurrent moderators see each other's claims, releases, and workflow actions without polling.
Accomplishments that we're proud of
- Fully native Reddit experience. Everything runs inside Devvit: serverless compute, Redis state, Realtime channels, and Reddit's moderator API. The only optional external call is OpenAI for AI features.
- AI that degrades gracefully. Every AI-powered feature (briefs, triage plans, spam evaluation) has a functional local fallback. The app is fully useful without an API key.
- 23-test formal workflow suite. The engine, normalization, and validation are verified independently of Reddit.
- Type-safe end-to-end. Shared types between client and server prevent contract drift.
- Operational impact. A single "Claim + brief" click replaces the multi-step flow of opening Modmail, reading, deciding ownership, writing a note, and drafting a reply.
What we learned
- Devvit Redis is powerful but demands careful key design when you need relational queries (claims by moderator, cases by status, events by time window).
- Modmail's API surface is richer than most moderators realize; the gap is in coordination and context, not raw data access.
- Local AI fallbacks need to match the interface of the full AI path exactly, or the workflow engine forks into two code paths that drift over time.
- Tutorial/demo mode is essential for hackathon judges and new moderators: it shows the full product without requiring live subreddit traffic.
What's next for ModFlow
- Bulk workflow actions across multiple threads in a single operation.
- Cross-subreddit dashboards so moderators of multiple communities see a unified queue.
- Modmail search and filtering inside the workspace (a top r/ModSupport request).
- Escalation paths that chain handoffs into multi-stage review workflows.
- Analytics dashboard with response time metrics, claim coverage rates, and moderator load balancing insights.
- Community rule enforcement profiles that let subreddits share and import workflow rule packs.
Built With
devvit · react · typescript · tailwind-css · vite · hono · redis · openai · reddit-api
Try It
- Install ModFlow on your subreddit from the Reddit App Directory.
- Open the subreddit menu → Create ModFlow Workspace.
- Open the custom post in expanded mode — your control room is live.
- Enable Tutorial Mode from the Stats tab to explore every feature with curated demo data.
- Optionally configure an OpenAI API key in app settings to unlock full AI-powered briefs, triage plans, and spam evaluation.
- Start claiming Modmail threads, building workflows, and shielding posts.
Log in or sign up for Devpost to join the conversation.