How nakuldevmv/spamurai works
Project Type and Purpose
• Spamurai is a backend service (Node.js) that automates spam cleanup in email inboxes.
• It fetches mail via IMAP, parses it, scans unsubscribe links for safety, clicks them, logs actions to MongoDB, and optionally moves or deletes messages.
Main Components
a. Orchestrator (backend/index.js)
b. Configuration (.env / example.env)
c. IMAP Connector (utils/connectMail/imapConnect.js)
d. Mail Filter & Parser (utils/getters.js)
e. Unsubscribe Module
• Link Extractor (utils/unsub/findUnsubLinks.js)
• Puppeteer Setup (utils/unsub/pupSetup.js)
• Captcha Handler (utils/unsub/captcha.js)
• Unsubscriber Logic (utils/unsub/unsubscriber.js)
f. Link Safety Scanner (utils/scanners/ipqs.js)
g. URL Checker (utils/urlChecker.js)
h. Mail Cleanup (utils/connectMail/imap-copy.js or variant)
i. MongoDB Client / Logger (utils/server/mongoConnect.js)
j. Optional Static UI (index.html, index2.html, terms.html)
External Dependencies
• IMAP Server (Gmail)
• IPQualityScore API
• MongoDB Atlas
Determining Relationships & Flow
1. The Orchestrator loads Configuration.
2. It connects to the IMAP connector, which talks to the IMAP Server.
3. Fetched mails flow to the Parser (getters.js) to skip flagged/important messages.
4. Each message is handed off to the Unsubscribe Module’s Link Extractor.
5. Extracted links are passed to the Link Safety Scanner; safe links trigger Puppeteer Setup.
6. The Unsubscriber Logic clicks safe links (with Captcha support) and logs each action via the Mongo Client.
7. Completed messages are either Trashed or Deleted via the Mail Cleanup module.
8. All persistence (link logs, unsubscribe logs) goes to MongoDB Atlas.
Architectural Patterns & Design Principles
• Modular, single-responsibility components under utils/
• Configuration-driven orchestration (.env injection)
• Clear separation between:
• I/O (IMAP, Puppeteer)
• Business logic (parsing, scanning, unsubscribing)
• Persistence (MongoDB)
Final Checklist
[ ] Clear labels on every component (including file names if desired)
[ ] Separation of internal modules vs external systems vs DB