# nick-choudhary/emailvalidator architecture

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

- Interactive diagram: https://gitdiagram.com/nick-choudhary/emailvalidator
- Repository: https://github.com/nick-choudhary/emailvalidator

## Overview

##### Project type and purpose
- This is a Node.js helper library that can also run as a standalone microservice.
- Its core function is to check email validity via syntax checks, DNS (MX/A) lookups, and a live SMTP handshake, with Redis used as a cache layer.

##### File structure
- Top-level files:
- index.js – exposes the public API (`checkEmailAddress`, `getExternalIp`, `startWebServer`)
- package.json – dependencies (express, redis, dns, net, etc.)
- controllers/ directory:
- externalAddressController.js – obtains or validates the external IP
- validatorController.js – runs syntax checks, DNS queries, SMTP connection attempts, and interacts with Redis
- webServerController.js – sets up an Express HTTP server to expose the email-check API over GET requests

##### README for additional insights
- Describes two usage patterns:
a) As a module: synchronous method calls
b) As a microservice: HTTP GET on `/:email`
- Lists external dependencies: Redis (cache), DNS servers, SMTP servers, optional external IP lookup service

a. Main components
- Client (library user or HTTP client)
- API layer
– Module API (function calls)
– HTTP server (webServerController via Express)
- Controllers & Services
– ExternalAddressController
– ValidatorController
- Infrastructure
– Redis cache
– DNS resolvers (public Internet)
– SMTP server endpoints (public Internet)
b. Relationships & data flow
1. Client invokes `checkEmailAddress()` or sends GET `/email@domain.com`.
2. If external IP not provided, ExternalAddressController fetches it.
3. ValidatorController:
– Syntax validation
– Redis lookup by email (cache hit → return)
– DNS MX record lookup → if none, A record lookup
– TCP connect to mail exchanger on port 25 to verify live server
– Write result to Redis with TTL
4. Return result object back to client or HTTP response
c. Architectural patterns & design principles
- Modular controllers for separation of concerns
- Cache-aside pattern with Redis to avoid repeated network calls
- Single-process, event-driven Node.js microservice
d. Key technologies/frameworks
- Node.js (runtime)
- Express.js (web server)
- redis (node client)
- dns (built-in)
- net (built-in TCP sockets)

##### Detail
- Cache logic (check/insert).
- Fallback paths (if MX fails → A record).
- Configuration inputs (redisHost, redisPort, externalIpAddress).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client\n(Library User or HTTP Client)"]:::client

    %% API Layers
    Index["Library API\n(index.js)"]:::internal
    WebServer["HTTP Microservice Server\n(GET /:email)"]:::api

    %% Controllers
    ExternalAddr["ExternalAddressController\n(fetch external IP)"]:::internal
    Validator["ValidatorController\n(syntax → DNS → SMTP → cache)"]:::internal

    %% Infrastructure
    Redis["Redis Cache"]:::datastore
    DNS["DNS Resolvers"]:::external
    SMTP["SMTP Servers"]:::external

    %% Supporting Files
    Config["Configuration\n(package.json)"]:::internal
    Docs["Documentation\n(README.md)"]:::external

    %% Flow: Library API
    Client -->|"checkEmailAddress()"| Index
    Index -->|"invoke External IP & Validation"| ExternalAddr

    %% Flow: HTTP Microservice
    Client -->|"GET /:email"| WebServer
    WebServer -->|"invoke External IP & Validation"| ExternalAddr

    %% External IP fetch then validation
    ExternalAddr -->|"external IP"| Validator

    %% Validator pipeline
    Validator -->|"cache lookup"| Redis
    Redis -->|"cache miss"| Validator
    Validator -->|"DNS MX lookup"| DNS
    DNS -->|"fallback A record"| DNS
    DNS -->|"return records"| Validator
    Validator -->|"SMTP handshake (port 25)"| SMTP
    SMTP -->|"response"| Validator
    Validator -->|"write result with TTL"| Redis

    %% Return result
    Validator -->|"return result"| Index
    Validator -->|"return HTTP response"| WebServer

    %% Supporting files
    subgraph "Supporting Files"
        Config
        Docs
    end

    %% Click Events
    click Index "https://github.com/nick-choudhary/emailvalidator/blob/master/index.js"
    click WebServer "https://github.com/nick-choudhary/emailvalidator/blob/master/controllers/webServerController.js"
    click ExternalAddr "https://github.com/nick-choudhary/emailvalidator/blob/master/controllers/externalAddressController.js"
    click Validator "https://github.com/nick-choudhary/emailvalidator/blob/master/controllers/validatorController.js"
    click Config "https://github.com/nick-choudhary/emailvalidator/blob/master/package.json"
    click Docs "https://github.com/nick-choudhary/emailvalidator/blob/master/README.md"

    %% Styles
    classDef client fill:#FFD580,stroke:#333,stroke-width:1px
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#FFA500,stroke:#333,stroke-width:1px
    classDef datastore fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
