# otwl/emailverifier architecture

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

- Interactive diagram: https://gitdiagram.com/otwl/emailverifier
- Repository: https://github.com/otwl/emailverifier

## Overview

EmailVerifier is an Express API that accepts authenticated, rate-limited email verification requests and returns format, domain, MX, disposable-provider, role, and free-provider results. Its request handler checks the cache, performs validation and lookups, assembles the response, and caches successful results. The README also documents health endpoints. The source excerpts show these runtime relationships directly; domain and provider list modules are data consumed by the handler.

Main entry points: [`index.js`](https://github.com/otwl/emailverifier/blob/main/index.js) (Email endpoint), [`domains.js`](https://github.com/otwl/emailverifier/blob/main/domains.js) (Trusted domains), [`emailRoles.js`](https://github.com/otwl/emailverifier/blob/main/emailRoles.js) (Role list), [`freeEmailProvider.js`](https://github.com/otwl/emailverifier/blob/main/freeEmailProvider.js) (Free-provider list)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API service"]
  node_entry["Express server<br/>[index.js]"]
  node_health["Health checks<br/>[index.js]"]
  node_auth["Secret authentication<br/>[index.js]"]
  node_limits["Rate limiting<br/>[index.js]"]
  node_handler["Email endpoint<br/>[index.js]"]
end

subgraph group_verify["Verification"]
  node_format["Format validation<br/>[index.js]"]
  node_domain["Domain verification<br/>[index.js]"]
  node_mx["MX lookup<br/>[index.js]"]
  node_disposable["Disposable detection<br/>[index.js]"]
  node_role["Role detection<br/>[index.js]"]
  node_free["Free-provider detection<br/>[index.js]"]
end

subgraph group_reference["Reference data"]
  node_trusted["Trusted domains<br/>[domains.js]"]
  node_roles["Role list<br/>[emailRoles.js]"]
  node_providers["Free-provider list"]
end

subgraph group_state["Caching"]
  node_cache[("LRU result cache<br/>[index.js]")]
end

node_client(("API client"))
node_dns["DNS resolver"]
node_disposablelib["Disposable-domain library"]

node_client -->|"sends requests"| node_entry
node_entry -->|"routes health"| node_health
node_entry -->|"checks secrets"| node_auth
node_entry -->|"limits email"| node_limits
node_entry -->|"routes email"| node_handler
node_handler -->|"reads cache"| node_cache
node_handler -->|"validates format"| node_format
node_handler -->|"validates domain"| node_domain
node_domain -->|"checks list"| node_trusted
node_domain -->|"looks up domain"| node_dns
node_handler -->|"checks MX"| node_mx
node_mx -->|"resolves MX"| node_dns
node_handler -->|"checks address"| node_disposable
node_disposable -->|"queries library"| node_disposablelib
node_handler -->|"detects role"| node_role
node_role -->|"checks list"| node_roles
node_handler -->|"checks provider"| node_free
node_free -->|"checks list"| node_providers
node_handler -->|"writes result"| node_cache
node_handler -->|"returns response"| node_client

click node_entry "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_health "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_auth "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_limits "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_handler "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_format "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_domain "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_mx "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_disposable "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_role "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_free "https://github.com/otwl/emailverifier/blob/main/index.js"
click node_trusted "https://github.com/otwl/emailverifier/blob/main/domains.js"
click node_roles "https://github.com/otwl/emailverifier/blob/main/emailRoles.js"
click node_providers "https://github.com/otwl/emailverifier/blob/main/freeEmailProvider.js"
click node_cache "https://github.com/otwl/emailverifier/blob/main/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_health,node_auth,node_limits,node_handler,node_client toneBlue
class node_format,node_domain,node_mx,node_disposable,node_role,node_free toneAmber
class node_trusted,node_roles,node_providers toneMint
class node_cache toneRose
class node_dns,node_disposablelib toneIndigo
```

## Components

### API service

- [Express server](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [Health checks](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [Secret authentication](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [Rate limiting](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [Email endpoint](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`

### Verification

- [Format validation](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [Domain verification](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [MX lookup](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [Disposable detection](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [Role detection](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`
- [Free-provider detection](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`

### Reference data

- [Trusted domains](https://github.com/otwl/emailverifier/blob/main/domains.js): `domains.js`
- [Role list](https://github.com/otwl/emailverifier/blob/main/emailRoles.js): `emailRoles.js`
- [Free-provider list](https://github.com/otwl/emailverifier/blob/main/freeEmailProvider.js): `freeEmailProvider.js`

### Caching

- [LRU result cache](https://github.com/otwl/emailverifier/blob/main/index.js): `index.js`

### Other components

- **API client**
- **DNS resolver**
- **Disposable-domain library**

## Connections

- API client → Express server: sends requests (evidence: `README.md`)
- Express server → Health checks: routes health (evidence: `index.js`)
- Express server → Secret authentication: checks secrets (evidence: `index.js`)
- Express server → Rate limiting: limits email (evidence: `index.js`)
- Express server → Email endpoint: routes email (evidence: `index.js`)
- Email endpoint → LRU result cache: reads cache (evidence: `index.js`)
- Email endpoint → Format validation: validates format (evidence: `index.js`)
- Email endpoint → Domain verification: validates domain (evidence: `index.js`)
- Domain verification → Trusted domains: checks list (evidence: `index.js`)
- Domain verification → DNS resolver: looks up domain (evidence: `index.js`)
- Email endpoint → MX lookup: checks MX (evidence: `index.js`)
- MX lookup → DNS resolver: resolves MX (evidence: `index.js`)
- Email endpoint → Disposable detection: checks address (evidence: `index.js`)
- Disposable detection → Disposable-domain library: queries library (evidence: `index.js`)
- Email endpoint → Role detection: detects role (evidence: `index.js`)
- Role detection → Role list: checks list (evidence: `index.js`)
- Email endpoint → Free-provider detection: checks provider (evidence: `index.js`)
- Free-provider detection → Free-provider list: checks list (evidence: `index.js`)
- Email endpoint → LRU result cache: writes result (evidence: `index.js`)
- Email endpoint → API client: returns response (evidence: `README.md`)
