Elevator pitch: Mod Vanguard is a Reddit-native moderation command center that turns report bursts, case ownership, decisions, appeals, rule trends, and audit history into one shared workflow for human moderators.

Mod Vanguard is a Devvit Web app for subreddit moderation teams. It is built for teams that need more than a raw report queue: they need context, ownership, precedent, appeal history, rule-level feedback, and a clean audit trail without leaving the Reddit-installed workflow.

The product stays human-in-the-loop. Mod Vanguard organizes the work; moderators still make the final moderation decisions.

• Hackathon Submission
• At A Glance
• What Problem It Solves
• Core Ideas
• Feature Matrix
• Screenshot Gallery
• Feature Guide
• End-To-End Moderator Workflow
• Architecture
• Devvit Integration
• Safety And Privacy
• Project Impact
• Submission Strengths
• Demo Video
• Run It Locally
• Devvit Playtest
• Demo Seed
• Quality Gate
• Useful Scripts
• Repository Map
• Out Of Scope

Submission description:

Mod Vanguard is a Devvit Web moderation workspace that converts reports, moderator menu actions, appeals, and final decisions into structured casefiles. Moderators can triage queue pressure, claim cases, review target context, reuse prior decision memory, resolve appeals with linked history, inspect rule drift, export audit records, and monitor live intake health from one Reddit-installed app.

Back to top

Back to top

Moderation breaks down when the context is scattered. A team may see reports in one place, mod notes somewhere else, prior decisions in memory, appeal history in another thread, and runtime health nowhere at all. That creates repeated questions:

• Which case is urgent?
• Has another moderator already started on it?
• What exact target are we deciding on?
• Are the reports clustered or isolated?
• Have we ruled on similar marketplace or trust issues before?
• Did an appeal connect back to the original decision?
• Can we export a scoped explanation later?
• Are report triggers, menu actions, and scheduled jobs actually arriving?

Mod Vanguard turns those questions into visible workflow surfaces.

Back to top

Every meaningful review target becomes a casefile. A casefile links the target, report pressure, readiness checks, ownership, timeline, prior decisions, and final moderator action.

Report Radar clusters repeated reports against the same target. A moderator sees the pressure level, count, timing, reasons, and linked case rather than reconstructing the burst manually.

The app never auto-removes, auto-approves, bans, locks, mutes, or decides an appeal. It surfaces context and records the decision a moderator explicitly makes.

Decision Memory and Rule Ops are designed around the active subreddit. They do not join data across communities and do not create public moderator rankings.

Signal Intake shows whether event streams are arriving, whether payloads were quarantined, and whether scheduled automation has run. This prevents a polished dashboard from hiding broken runtime inputs.

Back to top

Back to top

Triage and case review	Appeals and precedent

Protection and trust workflows	Coaching and rule operations

Runtime readiness	Signal health

Back to top

The Dashboard is the command deck. It starts with the current moderation queue, urgent cases, report heat, reviewable media, and the most important lanes for the next moderator action.

What it shows:

• Open case volume.
• Urgent lane count.
• Report count and report pressure.
• Media review load.
• Triage lanes such as fast review, second opinion, unclaimed, and media.
• Report pressure spotlight cards.
• Direct links into the next casefile.

Why it matters:

• Moderators can scan pressure before opening individual cases.
• High-pressure clusters stay visible instead of being buried in separate reports.
• The first screen is useful even when the queue is large.

Back to top

Report Radar turns many independent reports into one visible cluster. Each cluster carries enough context to decide whether the team should open a linked case immediately.

What it shows:

• Pressure tier.
• Report count.
• Reason count.
• Heat score.
• First report time.
• Latest report time.
• Report reasons.
• Linked case action.

Why it matters:

• Moderators can distinguish routine reports from coordinated pressure.
• The team avoids double-counting a burst as unrelated work.
• A report cluster can become the entry point into a structured casefile.

Back to top

Casefile Lens is the detailed review surface. It keeps target context, report pressure, readiness checks, signals, ownership, related memory, timeline, and decision controls in one route.

Supported target types:

• Text posts.
• Image posts.
• Link posts.
• Comments.
• Modmail-style records.
• Incident shells.

What it shows:

• Target title, author/community context, type, and source.
• Team state and ownership.
• Linked report cluster.
• Signals and readiness checks.
• Target snapshot.
• Decision panel.
• Related prior memory.
• Timeline.

Why it matters:

• Moderators do not have to remember context across screens.
• Review readiness is explicit.
• The final decision is grounded in the same visible record the team can later audit.

Back to top

Claim and Handoff prevents duplicate work by making ownership visible. A moderator can claim a case, release it, or request a second opinion.

What it supports:

• Claiming a case.
• Releasing a claim.
• Requesting another moderator.
• Scheduler-backed stale-claim expiry.
• Timeline events for ownership changes.

Why it matters:

• Two moderators are less likely to work the same case unknowingly.
• Second-opinion requests become part of the workflow, not a side conversation.
• Stale ownership can be cleaned up automatically.

Back to top

Decision Memory stores final moderation decisions in a searchable form. Each decision records action, rule tag, note, moderator, timestamp, and linked case.

What it shows:

• Searchable prior rulings.
• Rule-tagged decisions.
• Action filters.
• Strongest match result.
• Links back to source cases.

Why it matters:

• Similar cases can be handled consistently.
• Marketplace safety and trust decisions become reusable precedent.
• Moderators can search before acting instead of relying on memory.

Back to top

Appeals Desk keeps later disputes attached to the original case and decision history. It gives moderators appeal context without letting the system auto-judge the appeal.

What it shows:

• Appeal queue.
• Appeal status filters.
• Linked case context.
• Original decision history.
• Appeal timeline.
• Outcome controls.

Why it matters:

• Appeals are not detached from the original review.
• Moderators can see what happened before resolving the dispute.
• Outcomes become part of the same audit trail.

Back to top

Raid Shield focuses on coordinated report pressure and surge review. It uses existing report and case data to highlight work that could overload the queue.

What it shows:

• Coordinated signals.
• High-pressure clusters.
• Surge-linked cases.
• First stabilization lane.

Why it matters:

• Moderators can respond to pressure patterns before the queue scatters.
• Surge cases are grouped into a review lane.
• The team gets a specific "stabilize first" surface.

Back to top

Trust Adapter helps moderators compare risky targets against subreddit-specific trust memory. It is especially useful for source, author, marketplace, and link-pattern review.

What it shows:

• Targets needing trust context.
• Trust-sensitive report clusters.
• Prior approved and removed marketplace decisions.
• Local trust calibration memory.

Why it matters:

• Trust decisions are local to a community.
• Moderators can compare a target against prior subreddit behavior.
• Repeat low-trust patterns become visible without joining data across subreddits.

Back to top

Compassion Guard makes moderator workload and handoff risk visible. It is built for high-pressure moments where speed can hurt judgment.

What it shows:

• Urgent cases.
• Second-opinion pressure.
• Appeal load.
• Hot report clusters.
• Handoff recommendation.

Why it matters:

• The team can slow down on cases that deserve another look.
• Moderators can route high-pressure work before fatigue affects decisions.
• Compassion is treated as workflow design, not decoration.

Back to top

Mod Mentor turns live cases into coaching prompts for newer moderators. It gives a newer mod a reviewable case, precedent to compare, and prompts that keep the decision consistent.

What it shows:

• Cases for mentored review.
• Coaching prompts.
• Prior precedent.
• Rule-fit reminders.
• Second-opinion checks.

Why it matters:

• New moderators can learn from real workflow context.
• Training stays connected to the current queue.
• The system supports better human judgment without taking the decision away.

Back to top

Rule Ops summarizes rule activity inside the current subreddit. It focuses on rule friction rather than moderator performance.

What it shows:

• Cases by rule.
• Reports by rule.
• Decisions by rule.
• Appeals by rule.
• Action distribution.
• Repeat patterns.
• Drift signals.
• Time windows.

Why it matters:

• Moderators can see which rules are producing workload.
• Rules with repeated appeals or report pressure become easier to inspect.
• The team can tune rules from evidence instead of anecdotes.

Back to top

Audit Trail lists case, decision, appeal, and workflow events. It supports scoped filtering and export.

What it shows:

• Timeline events.
• Case filters.
• Appeal filters.
• Date filters.
• JSON export.
• CSV export.
• Packet scope.

Why it matters:

• Moderators can explain what happened later.
• Exports are scoped to visible filters.
• Auditability does not require exposing unrelated data.

Back to top

Settings shows available workflow switches and readiness signals. It separates implemented route-backed workflows from future ideas.

What it shows:

• Enabled workflow count.
• Route-backed workflow switches.
• Install surface readiness.
• Data boundary readiness.
• Human-control readiness.

Why it matters:

• Reviewers can see the shipped workflows are enabled.
• Moderators can confirm the app shape before relying on it.
• The route-backed settings page avoids pretending unfinished features are live.

Back to top

Signal Intake is the runtime health surface. It shows whether reports, menu actions, scheduled jobs, quarantined payloads, and failures are flowing through the system.

What it shows:

• Event freshness.
• Event counters.
• Automation runs.
• Failed actions.
• Quarantined payloads.
• Dead-letter states.
• Refresh control.

Why it matters:

• Moderators can tell if the app is receiving live signals.
• Malformed payloads do not silently disappear.
• A healthy-looking dashboard can be checked against actual intake state.

Back to top

The core flow is intentionally linear: pressure becomes a casefile, a moderator claims the work, precedent informs the ruling, and the final record stays searchable and auditable.

sequenceDiagram
  participant Reports as Report pressure
  participant Dashboard as Dashboard
  participant Casefile as Casefile Lens
  participant Memory as Decision Memory
  participant Audit as Audit Trail
  participant Mod as Moderator

  Reports->>Dashboard: Cluster repeated reports
  Dashboard->>Casefile: Open linked case
  Mod->>Casefile: Claim review
  Casefile->>Memory: Show related precedent
  Mod->>Casefile: Record action, rule tag, and note
  Casefile->>Audit: Append timeline event
  Audit->>Memory: Preserve searchable decision record

1. A target receives repeated reports.
2. Report Radar groups those reports into a pressure cluster.
3. Dashboard surfaces the cluster in the report pressure spotlight.
4. A moderator opens the linked casefile.
5. Casefile Lens shows target context, readiness, signals, linked reports, and related memory.
6. The moderator claims the case.
7. The moderator reviews prior marketplace or rule precedent.
8. The moderator records an action, rule tag, and note.
9. The case timeline receives the final decision event.
10. Decision Memory makes that ruling searchable.

Back to top

1. A later appeal enters Appeals Desk.
2. The appeal is linked to the original case.
3. The moderator reviews original decision history.
4. The moderator records an appeal outcome.
5. Audit Trail captures the case and appeal events.
6. JSON or CSV export provides a scoped record.

Back to top

1. Rule Ops aggregates cases, reports, decisions, and appeals.
2. The team inspects a rule such as Marketplace safety.
3. Repeated friction, action distribution, and drift signals become visible.
4. Moderators can open related cases or decisions from the rule view.
5. The team can adjust moderation practice with evidence.

Back to top

1. A moderator opens Signal Intake.
2. The team checks event freshness and counters.
3. Failed actions or quarantined payloads are visible.
4. Scheduler runs confirm claim expiry automation.
5. The team can trust, debug, or pause the demo based on real intake state.

Back to top

Mod Vanguard has four layers:

• Devvit runtime inputs receive Reddit menu actions, report triggers, and scheduled jobs.
• Server adapters and services normalize input, validate contracts, enforce idempotency, and update state.
• Devvit Redis stores subreddit-scoped cases, claims, decisions, appeals, reports, audit events, and ingestion telemetry.
• React Devvit Web UI gives moderators the dashboard, casefile, appeals, protection views, rule ops, audit, settings, and signal intake.

flowchart LR
  Reddit["Reddit post, comment, report, or subreddit menu"] --> Devvit["Devvit menu action, trigger, or scheduler"]
  Devvit --> Adapter["Input adapter"]
  Adapter --> Validation["Zod validation and idempotency"]
  Validation --> Services["Case, claim, decision, appeal, report, rule ops, audit, ingestion services"]
  Services --> Redis["Devvit Redis"]
  Redis --> Routes["Hono API routes"]
  Routes --> Client["React Devvit Web UI"]
  Client --> Moderator["Human moderator"]
  Moderator --> Routes

flowchart TB
  Report["Post or comment report"] --> Adapter["Report trigger adapter"]
  Menu["Moderator menu action"] --> MenuAdapter["Menu action adapter"]
  Scheduler["Claim expiry scheduler"] --> SchedulerAdapter["Scheduler adapter"]

  Adapter --> Contract["Shared Zod contracts"]
  MenuAdapter --> Contract
  SchedulerAdapter --> Contract

  Contract --> Idempotency["Idempotency guard"]
  Idempotency --> Services["Case, report, claim, appeal, decision, audit, ingestion services"]
  Services --> RedisKeys["Canonical Redis keys"]
  RedisKeys --> UI["Devvit Web command center"]
  Services --> DeadLetters["Dead letters and processing errors"]
  DeadLetters --> Intake["Signal Intake"]

flowchart LR
  Dashboard["Dashboard"] --> Casefile["Casefile Lens"]
  Casefile --> Claim["Claim / Handoff"]
  Casefile --> DecisionPanel["Decision Panel"]
  DecisionPanel --> Memory["Decision Memory"]
  Memory --> Appeals["Appeals Desk"]
  Appeals --> Audit["Audit Trail"]
  Dashboard --> Raid["Raid Shield"]
  Dashboard --> Trust["Trust Adapter"]
  Dashboard --> Compassion["Compassion Guard"]
  Casefile --> Mentor["Mod Mentor"]
  Memory --> RuleOps["Rule Ops"]
  Settings["Settings"] --> Intake["Signal Intake"]

flowchart LR
  CaseEvent["Case opened, claimed, or updated"] --> Timeline["Case timeline"]
  Decision["Moderator decision"] --> Timeline
  Appeal["Appeal outcome"] --> Timeline
  Timeline --> AuditIndex["Audit event index"]
  AuditIndex --> Filters["Scoped filters"]
  Filters --> Json["JSON export"]
  Filters --> Csv["CSV export"]
  Filters --> Reviewer["Moderator or judge review"]

flowchart TB
  Root["#/ Dashboard"] --> Cases["#/cases/:id"]
  Root --> AppealsRoute["#/appeals"]
  Root --> DecisionsRoute["#/decisions/search"]
  Root --> RaidRoute["#/raid-shield"]
  Root --> TrustRoute["#/trust-adapter"]
  Root --> CompassionRoute["#/compassion-guard"]
  Root --> MentorRoute["#/mod-mentor"]
  Root --> RuleRoute["#/rule-ops"]
  Root --> AuditRoute["#/audit"]
  Root --> SettingsRoute["#/settings"]
  SettingsRoute --> IntakeRoute["#/settings/ingestion"]

More detail: docs/architecture.md.

Back to top

The app is configured in devvit.json.

Relevant Reddit Developer docs:

• Mod Tool Quickstart
• Devvit Web overview
• Devvit Web configuration
• Triggers
• Scheduler
• Redis

Back to top

Mod Vanguard is intentionally conservative:

• No automatic remove, approve, ban, lock, mute, or appeal outcome without moderator confirmation.
• No cross-subreddit joins.
• No public moderator ranking or shaming surface.
• No external API dependency in the core demo path.
• No secrets in code or committed files.
• Moderator-scoped routes are protected by the permission guard.
• Audit exports contain only subreddit-scoped moderation workflow records.

Privacy detail: docs/privacy.md.

Back to top

Mod Vanguard is designed for communities where moderation is a repeated workflow with reports, precedent, trust patterns, appeals, and team coordination.

Broader impact:

• Less duplicate work because claim ownership is visible.
• Faster decisions because target context and report pressure are linked.
• More consistency because prior decisions are searchable.
• Easier handoffs because timelines, second opinions, and appeal links stay attached.
• Better accountability because audit export is scoped and explicit.

Back to top

Back to top

Public 60-second demo: youtu.be/SZ0vM9E-Lf0

Demo script and click path: docs/demo-script.md.

Back to top

Requirements:

• Node.js compatible with the project toolchain.
• pnpm 10.x. The lockfile currently uses pnpm@10.26.2.
• Devvit CLI access for real playtest runs.

Install dependencies:

pnpm install

Run the local preview:

pnpm preview:local

Use another port if needed:

PORT=5175 pnpm preview:local

Local preview is for browser smoke testing and screenshots. Real Reddit, Redis, menu action, report trigger, and scheduler data comes from Devvit playtest.

Back to top

Configured test subreddit:

r/mod_vanguard_dev

Run:

pnpm devvit:playtest

Live playtest checklist:

1. Run pnpm build and pnpm build:server.
2. Run pnpm devvit:playtest.
3. Open the playtest app in r/mod_vanguard_dev.
4. Use the subreddit menu to create the Mod Vanguard dashboard post.
5. Use the post/comment menu item on a test target and confirm a case appears in the dashboard.
6. Submit or replay post/comment report payloads and confirm Report Radar and Signal Intake update.
7. Leave a claim long enough for the scheduler path to run, then confirm stale claim telemetry appears.
8. Record a moderator decision, open Decision Memory, and verify the prior decision is searchable.
9. Export an Audit Trail slice and confirm it only contains subreddit-scoped moderation workflow records.

Back to top

Dry run is the default:

pnpm seed --dry-run

Live runtime seed:

MODCASE_BASE_URL=<playtest-or-runtime-url> pnpm seed --live

The seed creates a prior marketplace decision and sends report trigger payloads for the current demo target. Live writes require both a reachable Devvit playtest/runtime URL and the explicit --live flag.

Back to top

Before handing this to reviewers or judges, run:

pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm build:server
pnpm format
pnpm generate:demo-content
pnpm seed --dry-run

Known build warnings are documented in docs/qa.md. They are non-fatal bundler warnings from the current dependency/app shape.

Back to top

Back to top

docs/
  architecture.md                  System design and route map
  demo-script.md                   60-second and full walkthrough scripts
  devvit-capability-checklist.md   Runtime capability status
  privacy.md                       Data boundary and safety notes
  qa.md                            Manual and automated QA checklist
  screenshots/                     README screenshots captured from local preview
scripts/
  preview-local.mjs                Local static app plus mock API server
  seed-demo.ts                     Dry-run/live seed scenario
src/client/
  App.tsx                          App shell and navigation
  routes/                          Dashboard, casefile, appeals, rule ops, audit, settings
  components/                      Shared UI primitives and target renderers
  lib/api.ts                       Typed API client and local mock mode
  lib/mocks/                       Schema-valid local preview fixtures
src/server/
  adapters/                        Devvit menu, report, and scheduler adapters
  routes/                          Hono API and internal runtime routes
  services/                        Case, decision, appeal, report, rule ops, audit logic
  storage/                         Redis wrapper, codecs, and canonical key builders
src/shared/
  api/contracts.ts                 Zod request/response contracts
  types/                           Shared domain types

Back to top

Mod Vanguard does not try to replace moderators. It does not perform final enforcement by itself, it does not create public moderator scoreboards, and it does not join data across subreddits. The goal is to make human review faster, more consistent, and easier to audit.

Back to top