# nakuldevmv/spamurai architecture

> Architecture diagram of the GitHub repository nakuldevmv/spamurai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nakuldevmv/spamurai
- Repository: https://github.com/nakuldevmv/spamurai

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration
    Config[".env / example.env"]:::config

    %% External Services
    subgraph "External Services"
        direction TB
        IMAPServer["IMAP Server (Gmail)"]:::external
        IPQS["IPQualityScore API"]:::external
    end

    %% Databases
    subgraph "Databases"
        direction TB
        MongoAtlas["MongoDB Atlas"]:::database
    end

    %% Spamurai Service
    subgraph "Spamurai Service"
        direction TB
        Orchestrator["Orchestrator (index.js)"]:::internal
        IMAPConnector["IMAP Connector (imapConnect.js)"]:::internal
        Parser["Mail Filter & Parser (getters.js)"]:::internal
        UnsubLinkExtractor["Link Extractor (findUnsubLinks.js)"]:::internal
        URLScanner["Link Safety Scanner (ipqs.js)"]:::internal
        URLChecker["URL Checker (urlChecker.js)"]:::internal
        PuppeteerSetup["Puppeteer Setup (pupSetup.js)"]:::internal
        CaptchaHandler["Captcha Handler (captcha.js)"]:::internal
        Unsubscriber["Unsubscriber Logic (unsubscriber.js)"]:::internal
        MailCleanup["Mail Cleanup (imapConnectBackup_new.js)"]:::internal
        MongoLogger["MongoDB Client / Logger (mongoConnect.js)"]:::internal
    end

    %% UI (Optional)
    subgraph "Static UI (Optional)"
        direction TB
        Home["Home Page (index.html)"]:::ui
        Alt["Alternate Page (index2.html)"]:::ui
        Terms["Terms Page (terms.html)"]:::ui
        User["User"]:::external
        User --> Home
    end

    %% Orchestration & Flow
    Config -.-> Orchestrator
    Orchestrator -->|"connect"| IMAPConnector
    IMAPConnector -->|"fetch mail"| Parser
    Parser -->|"parsed messages"| UnsubLinkExtractor
    UnsubLinkExtractor -->|"links"| URLScanner
    URLScanner -->|"POST /check"| IPQS
    URLScanner -->|"safe link"| PuppeteerSetup
    PuppeteerSetup --> CaptchaHandler
    CaptchaHandler --> Unsubscriber
    Unsubscriber -->|"click link"| IMAPServer
    Unsubscriber -->|"log action"| MongoLogger
    MongoLogger -->|"save record"| MongoAtlas
    Unsubscriber -->|"cleanup"| MailCleanup
    MailCleanup -->|"move/delete"| IMAPServer
    URLChecker -->|"validate URL"| URLScanner

    Orchestrator --> URLChecker
    Orchestrator --> MongoLogger

    %% Click Events
    click Config "https://github.com/nakuldevmv/spamurai/blob/main/backend/example.env"
    click Orchestrator "https://github.com/nakuldevmv/spamurai/blob/main/backend/index.js"
    click IMAPConnector "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/connectMail/imapConnect.js"
    click Parser "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/getters.js"
    click UnsubLinkExtractor "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/unsub/findUnsubLinks.js"
    click PuppeteerSetup "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/unsub/pupSetup.js"
    click CaptchaHandler "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/unsub/captcha.js"
    click Unsubscriber "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/unsub/unsubscriber.js"
    click URLScanner "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/scanners/ipqs.js"
    click URLChecker "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/urlChecker.js"
    click MailCleanup "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/connectMail/imapConnectBackup_new.js"
    click MongoLogger "https://github.com/nakuldevmv/spamurai/blob/main/backend/utils/server/mongoConnect.js"
    click Home "https://github.com/nakuldevmv/spamurai/blob/main/index.html"
    click Alt "https://github.com/nakuldevmv/spamurai/blob/main/index2.html"
    click Terms "https://github.com/nakuldevmv/spamurai/blob/main/terms.html"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef external fill:#F0F0F0,stroke:#888888,color:#555555;
    classDef database fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef config fill:#FFF5CC,stroke:#e09f3e,color:#e09f3e;
    classDef ui fill:#EAD7F2,stroke:#6f42c1,color:#6f42c1;
```
