🛡️ ModGuard — Warning & Strike System for Reddit

A Devvit app that gives Reddit moderators a structured, automated warning system — issue warnings, track strike history, and auto-escalate to bans when thresholds are reached.

---

🚨 The Problem

Reddit communities rely entirely on volunteer moderators to keep discussions healthy. But today, mods have almost no structured tooling for progressive discipline:

• There is no built-in way to issue a formal warning to a user before banning them
• Mod actions are scattered — ban logs, modmail threads, and spreadsheets don't talk to each other
• New moderators have no visibility into a user's history — they might ban someone who already received warnings, or let repeat offenders slide
• Users get banned with no context or escalation path, which damages community trust
• There is no automation — every escalation (warn → temp ban → perm ban) is done manually

The result: inconsistent moderation, frustrated users, and burnout for mods.

---

✅ What ModGuard Achieves

ModGuard brings structured, transparent, and automated moderation directly into Reddit:

Feature	Description
One-click warnings	Issue a warning from any post or comment via the ... overflow menu
Full warning history	Every warning is stored with rule violated, severity, note, and mod who issued it
Automatic escalation	At 3 warnings → auto temp ban (7 days). At 5 warnings → auto permanent ban
Mod dashboard	Pinned post showing live stats: total warnings, warned users, ban threshold
Full user drill-down	See every warning for any user, with timestamps and the post that triggered each one
Warning removal	Mods can remove incorrect warnings at any time
DM notifications	Users automatically receive a DM explaining each warning and the relevant rule
Configurable thresholds	Subreddit admins can adjust temp ban / perm ban thresholds and ban duration

---

🏘️ How This Helps Communities

For Moderators

• Consistent enforcement — every mod on the team sees the same warning history, preventing contradictory actions
• Audit trail — know exactly who warned whom, when, and why
• Reduced burnout — escalations happen automatically; mods don't have to remember to follow up
• Onboarding — new mods can immediately see a user's context before acting

For Users

• Fairness — instead of a sudden ban, users receive structured warnings with reasons
• Transparency — each warning includes the rule violated and a note from the mod
• Second chances — the graduated system gives users the opportunity to correct their behavior

For Communities

• Healthier discussions — consistent enforcement signals that rules are real and apply equally
• Trust — users know the process is fair, not arbitrary
• Lower churn — fewer "I got banned for no reason" complaints that damage community reputation

---

🏗️ Architecture

graph TD
    subgraph Reddit UI
        A[Post / Comment] -->|"... menu → ⚠️ Warn User"| B[Devvit Menu Item]
        D[Subreddit Menu] -->|"Open ModGuard Dashboard"| E[Create Dashboard Post]
    end

    subgraph ModGuard App - Devvit Platform
        B --> C[Hono Server\n/internal/menu/warn-from-post]
        C --> F[showForm: Warn User]
        F -->|Submit| G[Hono Server\n/internal/form/warn-submit]
        G --> H[issueWarning\ncore/warnings.ts]

        H --> I{Strike Count}
        I -->|"< 3"| J[Send DM to User\nreddit.sendPrivateMessage]
        I -->|">= 3"| K[Temp Ban 7 days\nreddit.banUser]
        I -->|">= 5"| L[Permanent Ban\nreddit.banUser]

        H --> M[(Redis\nWarnings Store)]

        N[Dashboard Post\nsplash.html] -->|Fetch /api/stats| O[Hono API\n/api/stats]
        P[Full Dashboard\ngame.html] -->|Fetch /api/users| Q[Hono API\n/api/users]
        P -->|DELETE /api/user/:id/warning/:wid| R[Remove Warning]

        O --> M
        Q --> M
        R --> M
    end

    subgraph Devvit Infrastructure
        M
        S[devvit.json\nApp Config]
    end

Loading

Data Flow — Issuing a Warning

Mod clicks "⚠️ Warn User"
        │
        ▼
Devvit calls POST /internal/menu/warn-from-post
        │  (looks up post author from Reddit API)
        ▼
showForm response → Reddit renders the form
        │  (username pre-filled, rule dropdown, severity, note)
        ▼
Mod fills form → clicks "Issue Warning"
        │
        ▼
Devvit calls POST /internal/form/warn-submit
        │
        ▼
issueWarning() saves to Redis
        │
        ├─ strike count < 3  →  DM sent to user
        ├─ strike count = 3  →  Temp ban (7 days) + DM
        └─ strike count ≥ 5  →  Permanent ban + DM
        │
        ▼
Dashboard post updates on next load (live from Redis)

---

📁 Project Structure

modguardgarg/
├── src/
│   ├── client/
│   │   ├── splash.tsx          # Inline dashboard (stats + recent warnings)
│   │   ├── game.tsx            # Full dashboard (user list + warning detail)
│   │   └── hooks/
│   │       ├── useDashboard.ts     # Fetch /api/stats
│   │       ├── useAllUsers.ts      # Fetch /api/users
│   │       └── useUserWarnings.ts  # Fetch /api/user/:username
│   ├── server/
│   │   ├── index.ts            # Hono app entry point
│   │   ├── core/
│   │   │   ├── warnings.ts     # Business logic: issue, remove, auto-ban
│   │   │   └── post.ts         # Create the dashboard post
│   │   └── routes/
│   │       ├── api.ts          # REST API for client dashboards
│   │       ├── menu.ts         # Menu item handlers (showForm)
│   │       ├── forms.ts        # Form submit handlers
│   │       └── triggers.ts     # onAppInstall trigger
│   └── shared/
│       └── api.ts              # Shared types + constants (Warning, Rules, Settings)
├── devvit.json                 # App config: menus, forms, triggers, server entry
└── vite.config.ts              # Vite + Devvit plugin build config

---

⚙️ Tech Stack

Layer	Technology
Platform	Devvit (Reddit's developer platform)
Server	Hono (lightweight TypeScript web framework)
Client	React + Tailwind CSS
Build	Vite with @devvit/start/vite plugin
Storage	Devvit Redis (built-in key-value store, per-subreddit)
Language	TypeScript (strict, end-to-end)

---

🚀 Installation

Prerequisites

Requirement	Version	Notes
Node.js	≥ 22.2.0	Download
npm	≥ 10	Bundled with Node
Devvit CLI	0.12.23	Installed below
Reddit account	—	Must be a moderator of a test subreddit

Step 1 — Clone the repo

git clone https://github.com/YOUR_USERNAME/modguard.git
cd modguard/modguardgarg

Step 2 — Install the Devvit CLI

npm install -g devvit@0.12.23

Step 3 — Log in to Reddit via Devvit

devvit login

This opens a browser window. Approve the OAuth prompt with the Reddit account that moderates your test subreddit.

Step 4 — Install dependencies

npm install

Step 5 — Create a test subreddit

Go to reddit.com/subreddits/create and create a private subreddit. You'll need to be a moderator of it.

Then update devvit.json → dev.subreddit to match your subreddit name:

"dev": {
  "subreddit": "your_subreddit_name"
}

Step 6 — Start the playtest

Windows users: Run this first in every new PowerShell session:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

devvit playtest
# or: npm run dev

Wait for:

✓ Playtest ready
➜ URL: https://www.reddit.com/r/your_subreddit/?playtest=modguardgarg

Open that URL in your browser. The ?playtest=modguardgarg query parameter must always be in the URL for the app to load.

Step 7 — Create the dashboard

On the subreddit page, click the ... menu next to the subreddit name → "Open ModGuard Dashboard". This creates a pinned dashboard post.

---

🧪 Testing the Full Flow

1. Open any post in the subreddit
2. Click ... → ⚠️ Warn User — fill in the form and submit
3. Check the dashboard post — warning appears under "Recent Warnings"
4. Click "Full Dashboard →" — see the user list with strike count
5. Click a user — see full warning history, click × to remove a warning

Note on auto-ban testing: Reddit's API prevents banning a subreddit moderator. To test the auto-ban, warn a non-moderator account 3 times — the temp ban will execute automatically.

---

🚢 Deploying (for production use)

npm run deploy    # type-check + lint + upload new version
npm run launch    # deploy + publish to Devvit app directory

After publishing, other subreddits can install ModGuard from the Devvit App Directory.

---

🛠️ Available Scripts

npm run dev          # Start live playtest (devvit playtest)
npm run build        # Build client + server to dist/
npm run deploy       # Type-check, lint, and upload to Devvit
npm run launch       # Deploy + publish to app directory
npm run type-check   # TypeScript type checking (tsc --build)
npm run lint         # ESLint on src/**
npm run prettier     # Format all files with Prettier
devvit login         # Authenticate with Reddit

---

🎮 How to Use

1. Create the Dashboard

Click the ... menu next to r/yoursubreddit → "Open ModGuard Dashboard". This creates a pinned dashboard post.

2. Warn a User

Navigate to any post or comment by a user you want to warn. Click ... → "⚠️ Warn User". Fill in:

• Rule Violated (from your subreddit's rule list)
• Note (optional context for your mod team)
• Severity (Warning or Final Warning)

Click "Issue Warning". The user receives a DM and the warning is logged.

3. View Warning History

Click ... on any post → "📋 View User Warnings" to jump to that user's Reddit profile with their full warning history visible in the dashboard.

4. Full Dashboard

From the dashboard post, click "Full Dashboard →" to open the expanded view — search users by name, see strike counts, drill into individual warnings, and remove incorrect ones.

5. Auto-Escalation

ModGuard automatically bans users when thresholds are crossed:

• 3 warnings → 7-day temporary ban
• 5 warnings → permanent ban

No manual action required.

---

⚙️ Configuration

Default thresholds (set at install time, configurable via ModGuard Settings):

Setting	Default	Description
tempBanThreshold	3	Warnings before temp ban
tempBanDays	7	Duration of temp ban in days
permBanThreshold	5	Warnings before permanent ban

---

🔒 Permissions & Safety

• Warning data is stored per-subreddit in isolated Redis keys — no data crosses subreddit boundaries
• Only moderators can issue warnings and access the full dashboard (enforced server-side)
• Warning removal requires a server-side moderator check via Reddit's API
• Users are always notified via DM when a warning is issued

---

🏆 Built for Reddit Mod Tools Hackathon 2026

ModGuard was built for the Reddit Mod Tools Hackathon 2026 with the goal of bringing professional-grade community management tooling to the 50,000+ active Reddit moderators who currently have no structured warning system.