Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Project: A Moderation Bot

Assemble a moderation bot core: join verification with a timeout, a spam pipeline, an escalating warning ladder, permission checks and an audit log, all testable with a fake clock.

This project assembles the chapter's pieces into one moderation core you could run on a community chat. It does four things: it verifies new members (they must press a button within a few minutes or they are removed), it screens every message through a spam pipeline, it escalates repeat offenders along a warning ladder, and it writes an audit log that moderators can read with a command.

The code is platform-neutral. Events come in as small objects (join, message, button, command), actions go out through an actions object that stands in for kick, mute and deleteMessage calls on Telegram or Discord. Wiring it to a real platform means writing a thin adapter, like those in command handler architecture.

flowchart TD
    J["join event"] --> PEND["pending verification (5 min)"]
    PEND -- "button pressed" --> OK["member verified"]
    PEND -- "timeout" --> KICK["kick + log"]
    MSG["message event"] --> CHK["spam pipeline: flood, links, mentions"]
    CHK -- "clean" --> PASS["allow"]
    CHK -- "violation" --> DEL["delete message"] --> W["warning ladder"]
    W --> ACT["note, mute, kick, ban"]
    ACT --> LOG[("audit log")]
    KICK --> LOG

Every action that changes something ends in the audit log.

The program

The program is long on purpose: it is a small complete system. Read it in sections, then run it.

Node.js Moderation core: verification, pipeline, ladder, audit log

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How the pieces fit

The pipeline is an array of functions. Adding a rule means adding a function to checks; removing one is deleting a line. Each check is easy to test alone: feed it a message and a clock.

Trust grows with time. The links check treats new members differently from members who have been around for a day. This is a very effective real-world rule: most link spam comes from accounts that joined minutes ago. Discord's own "verification level" and Telegram's join requests work on the same idea.

The verification sweep is the same pattern as the reminder bot. Deadlines are stored as absolute times and a periodic sweep looks for expired ones (reminder bot). If the bot restarts, the pending list must come back from the database, otherwise people who joined just before the restart would never be removed.

Everything that changes something is logged. Reading the audit log you can answer "why was ann muted?" without guessing. Real bots add the moderator ID for manual actions and send the entry to a log channel as well as storing it.

Hardening it for real use

  1. Persist state. Move pending, verified, warnings and audit into SQLite tables (SQLite storage) and rebuild nothing in memory except short-lived rate windows.
  2. Check permissions on commands. The callerIsMod flag must come from the platform (Discord member.permissions, Telegram getChatMember), as in moderation commands and permissions.
  3. Never act on staff. Before warnUser, skip anyone who has moderator permissions, otherwise the bot may mute its own admins.
  4. Be careful with automatic bans. Prefer mute and review for the first version, and turn on automatic bans only after you have watched the false-positive rate for a few weeks.
  5. Appeals and transparency. Tell the user why their message was removed (a short, polite direct message or a reply that deletes itself), and give a way to ask a human.
  6. Respect platform rules. Do not scrape or store more than you need. Say in your bot's description what it logs, and delete data when asked.
  7. Add tests. Use the fake clock to test the edge cases: verification at exactly 5 minutes, the sixth warning, an old warning expiring, a trusted member posting a link (testing bots with fakes).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the bot store a verification deadline instead of a timer per new member?

    Stored absolute deadlines can be reloaded after a restart and checked by a single sweep.
  2. 2. Why does the links check relax for members who have been around for a day?

    Time since joining is a cheap and effective signal that reduces false positives for regulars.
  3. 3. What should always happen when the bot takes a moderation action?

    An audit trail lets moderators review and reverse automatic decisions.
  4. 4. Which is a sensible hardening step before enabling automatic bans?

    Start with reversible actions, never act on staff, and measure mistakes first.

Summary

  • A moderation core is events in, actions out: verification, a pipeline of small checks, an escalation ladder and an audit log.
  • Use stored deadlines and periodic sweeps instead of one timer per member.
  • Let trust grow with time in the community, and exempt staff from automatic actions.
  • Persist state, take permissions from the platform, start with reversible actions and test with a fake clock.

Next: Practice exercises with solutions