ModShield

AI-assisted moderation triage copilot for Reddit moderators — built for the Reddit Mod Tools & Migrated Apps Hackathon 2026 (Best New Mod Tool).

ModShield reduces moderator workload with rule matching, AI triage suggestions, a sortable review queue, audit logging, and analytics — always human-in-the-loop (no autonomous bans).

---

Overview

Priority	How ModShield delivers
Community impact	Faster triage on spam, harassment, duplicates, low-effort posts
Polish	Reddit-native dark UI, badges, confidence indicators, empty states
Reliable UX	Mock AI by default; optional OpenAI/Anthropic with safe fallbacks
Ecosystem impact	Installable Devvit app with menu actions + live triggers
Fast installation	One-click setup menu + sample rules + demo seed
Demo value	60s script, seeded violations, local web dashboard for screenshots

---

Features

• Rule engine — keywords, regex, severity scoring, recommended actions
• AI triage — violationType, confidence, explanation, recommendedAction
• Moderator queue — sort by severity, confidence, or newest
• Audit log — moderator, AI recommendation, final outcome, timestamp
• Safety layer — human approval required; thresholds for surfacing only
• Analytics — estimated time saved, top violations, repeat offenders, trends
• Onboarding — setup wizard, sample rules import, demo queue seed

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Reddit (posts/comments)                  │
└───────────────────────────┬─────────────────────────────────┘
                            │ PostSubmit / CommentSubmit
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Devvit triggers → TriageEngine (rules + AI) → Queue (Redis)  │
└───────────────────────────┬─────────────────────────────────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
   Custom post UI    Menu actions      Audit + Analytics
   (mod dashboard)  (install/seed)    (mod accountability)

Modules

Path	Responsibility
src/moderation/	Rule engine + triage merge
src/ai/	OpenAI, Anthropic, mock providers
src/services/	Queue, audit, analytics, onboarding
src/storage/	Redis-backed JSON repository
src/components/	Devvit Blocks dashboard UI
web/	Optional Vite + Tailwind demo UI for recordings

---

Project structure

src/
  api/           Reddit triggers + content helpers
  ai/            Provider abstraction (OpenAI, Anthropic, mock)
  components/    Devvit Blocks UI
  config/        Defaults, env
  hooks/         Local demo hook (web)
  moderation/    Rule + triage engines
  services/      Domain services
  storage/       Redis keys + repository
  types/         Shared TypeScript types
  utils/         Text, time, validation
  main.tsx       Devvit entrypoint
web/             Screenshot-friendly React demo
docs/            Installation, deployment, demo, Devpost
tests/           Rule engine unit tests

---

Setup

Prerequisites

• Node.js 18+
• Reddit account + test subreddit (moderator)
• Devvit CLI (npm i -g devvit or use project devDependency)

Install

git clone <your-repo>
cd ModSheild
npm install
cp .env.example .env   # optional, for real AI keys

Environment variables

Variable	Required	Description
OPENAI_API_KEY	No	Enables OpenAI triage (falls back to mock)
OPENAI_MODEL	No	Default gpt-4o-mini
ANTHROPIC_API_KEY	No	Enables Anthropic triage
ANTHROPIC_MODEL	No	Default claude-3-5-sonnet-latest

Set Devvit secrets for production:

devvit secrets set OPENAI_API_KEY "sk-..."

---

Running locally

Devvit (live on test subreddit)

npm run devvit:login
npm run devvit:dev

Install the app on your test subreddit when prompted.

Web demo (screenshots / pitch deck)

npm run web:dev

Open http://localhost:5173 → Install → Seed demo queue → triage sample violations.

Typecheck & tests

npm run typecheck
npm run test

---

Deploying to Devvit

npm run devvit:deploy

See docs/DEPLOYMENT.md for versioning, secrets, and judge-ready checklist.

---

Demo walkthrough (moderator flow)

1. Install ModShield on r/YourTestSub
2. Subreddit menu → ModShield: Install / Setup
3. ModShield: Seed Demo Queue (4 sample violations)
4. ModShield: Open Dashboard → review queue sorted by severity
5. One-click Approve / Remove / Escalate / Dismiss (logged to audit)
6. ModShield: View Audit Log for accountability

Full script: docs/DEMO.md

---

Screenshots (placeholders)

#	Capture
1	Setup wizard / install toast
2	Queue sorted by severity with confidence badges
3	Spam card + suggested Remove
4	Harassment card + Escalate
5	Analytics panel (time saved, top violations)
6	Audit log toast / entry

Store under docs/screenshots/ when captured.

---

Future roadmap

• Multi-subreddit intelligence sharing
• Vector search / embeddings for duplicate detection
• Mod team roles & assignment
• Cross-community trend insights
• Integration with mod mail & removal reasons API

---

Hackathon category

Best New Mod Tool — net-new moderator functionality with clear ecosystem impact and installability.

• docs/WINNING_STRATEGY.md
• docs/DEVPOST.md

---

License

Apache-2.0