# eneelkant/email-validation-tool architecture

> Architecture diagram of the GitHub repository eneelkant/email-validation-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eneelkant/email-validation-tool
- Repository: https://github.com/eneelkant/email-validation-tool

## Overview

MailSure is a self-hosted email-verification product served through MCP transports and an optional verify-only website API, with a static browser UI. The principal workflow accepts a single address, batch, or CSV; validation combines syntax, domain/DNS and provider signals, normalizes a result, and can cache it. MCP also exposes domain checks, job controls, statistics and disposable-list administration. README documents SMTP/catch-all as optional and disabled by default. Several validator and CSV implementations were not sampled; those links are omitted or documented with the README as evidence.

Main entry points: [`src/validators/orchestrator.ts`](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/orchestrator.ts) (Validation Orchestrator), [`src/mcp/tools.ts`](https://github.com/eneelkant/email-validation-tool/blob/main/src/mcp/tools.ts) (MCP Tools), [`src/http/website-api.ts`](https://github.com/eneelkant/email-validation-tool/blob/main/src/http/website-api.ts) (Website API), [`src/runtime/lifecycle.ts`](https://github.com/eneelkant/email-validation-tool/blob/main/src/runtime/lifecycle.ts) (Runtime Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_http["HTTP Service<br/>[app.ts]"]
  node_mcp["MCP Server<br/>[server.ts]"]
  node_tools["MCP Tools<br/>[tools.ts]"]
  node_website_api["Website API<br/>[website-api.ts]"]
end

subgraph group_validation["Validation"]
  node_syntax["Syntax Checks<br/>[syntax.ts]"]
  node_orchestrator["Validation Orchestrator<br/>[orchestrator.ts]"]
  node_dns["DNS Checks<br/>[dns.ts]"]
  node_provider["Provider Classification<br/>[disposable.ts]"]
  node_free_provider["Free Providers<br/>[free-provider.ts]"]
  node_roles["Role Locals<br/>[role.ts]"]
  node_smtp["SMTP Diagnostics<br/>[smtp.ts]"]
  node_catch_all["Catch-all Checks<br/>[catch-all.ts]"]
  node_normalize["Result Normalization"]
  node_results["Result Schemas<br/>[results.ts]"]
end

subgraph group_jobs["Bulk Processing"]
  node_batch["Batch Validation<br/>[batch.ts]"]
  node_csv["CSV Jobs<br/>[csv.ts]"]
end

subgraph group_state["State and Operations"]
  node_db[("SQLite Cache and Jobs<br/>[db.ts]")]
  node_lifecycle["Runtime Lifecycle<br/>[lifecycle.ts]"]
  node_config["Runtime Configuration<br/>[env.ts]"]
  node_sync["Disposable Sync<br/>[disposable-sync.ts]"]
  node_bounded["Bounded HTTP Reads"]
end

subgraph group_website["Website"]
  node_frontend["Static Web UI<br/>[app.js]"]
  node_web_verify["Browser API Client<br/>[verify.js]"]
  node_web_csv["Browser CSV<br/>[csv.js]"]
  node_web_config["Frontend Config<br/>[config.js]"]
end

node_mcp_user(("MCP Client"))
node_browser(("Browser User"))

node_mcp_user -->|"uses"| node_mcp
node_mcp -->|"registers tools"| node_tools
node_http -->|"creates handler"| node_mcp
node_browser -->|"uses"| node_frontend
node_frontend -->|"calls"| node_web_verify
node_frontend -->|"uses"| node_web_csv
node_frontend -->|"reads config"| node_web_config
node_web_verify -->|"requests verification"| node_website_api
node_http -->|"mounts"| node_website_api
node_website_api -->|"validates"| node_orchestrator
node_website_api -->|"validates batches"| node_batch
node_tools -->|"validates"| node_orchestrator
node_tools -->|"validates batches"| node_batch
node_tools -->|"starts jobs"| node_csv
node_tools -->|"reads and writes"| node_db
node_orchestrator -.->|"checks syntax"| node_syntax
node_orchestrator -.->|"checks DNS"| node_dns
node_orchestrator -.->|"classifies domains"| node_provider
node_provider -->|"excludes overlaps"| node_free_provider
node_orchestrator -.->|"checks role locals"| node_roles
node_orchestrator -.->|"optionally checks"| node_smtp
node_orchestrator -.->|"optionally checks"| node_catch_all
node_website_api -->|"normalizes results"| node_normalize
node_tools -->|"normalizes results"| node_normalize
node_normalize -->|"shapes result"| node_results
node_batch -.->|"validates emails"| node_orchestrator
node_csv -.->|"processes batches"| node_batch
node_csv -.->|"tracks jobs"| node_db
node_http -->|"checks readiness"| node_lifecycle
node_lifecycle -->|"initializes"| node_db
node_lifecycle -->|"loads dataset"| node_provider
node_lifecycle -->|"loads dataset"| node_free_provider
node_db -->|"reads settings"| node_config
node_sync -->|"limits downloads"| node_bounded
node_sync -->|"replaces dataset"| node_provider
node_sync -->|"filters overlaps"| node_free_provider

click node_http "https://github.com/eneelkant/email-validation-tool/blob/main/src/http/app.ts"
click node_mcp "https://github.com/eneelkant/email-validation-tool/blob/main/src/mcp/server.ts"
click node_tools "https://github.com/eneelkant/email-validation-tool/blob/main/src/mcp/tools.ts"
click node_website_api "https://github.com/eneelkant/email-validation-tool/blob/main/src/http/website-api.ts"
click node_syntax "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/syntax.ts"
click node_orchestrator "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/orchestrator.ts"
click node_dns "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/dns.ts"
click node_provider "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/disposable.ts"
click node_free_provider "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/free-provider.ts"
click node_roles "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/role.ts"
click node_smtp "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/smtp.ts"
click node_catch_all "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/catch-all.ts"
click node_normalize "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/result-normalize.ts"
click node_results "https://github.com/eneelkant/email-validation-tool/blob/main/src/types/results.ts"
click node_batch "https://github.com/eneelkant/email-validation-tool/blob/main/src/processing/batch.ts"
click node_csv "https://github.com/eneelkant/email-validation-tool/blob/main/src/processing/csv.ts"
click node_db "https://github.com/eneelkant/email-validation-tool/blob/main/src/database/db.ts"
click node_lifecycle "https://github.com/eneelkant/email-validation-tool/blob/main/src/runtime/lifecycle.ts"
click node_config "https://github.com/eneelkant/email-validation-tool/blob/main/src/config/env.ts"
click node_sync "https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/disposable-sync.ts"
click node_frontend "https://github.com/eneelkant/email-validation-tool/blob/main/public/js/app.js"
click node_web_verify "https://github.com/eneelkant/email-validation-tool/blob/main/public/js/verify.js"
click node_web_csv "https://github.com/eneelkant/email-validation-tool/blob/main/public/js/csv.js"
click node_web_config "https://github.com/eneelkant/email-validation-tool/blob/main/public/js/config.js"
click node_bounded "https://github.com/eneelkant/email-validation-tool/blob/main/src/utils/bounded-response.ts"

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_http,node_mcp,node_tools,node_website_api,node_mcp_user,node_browser toneBlue
class node_syntax,node_orchestrator,node_dns,node_provider,node_free_provider,node_roles,node_smtp,node_catch_all,node_normalize,node_results toneAmber
class node_batch,node_csv toneMint
class node_db,node_lifecycle,node_config,node_sync,node_bounded toneRose
class node_frontend,node_web_verify,node_web_csv,node_web_config toneIndigo
```

## Components

### Interfaces

- [HTTP Service](https://github.com/eneelkant/email-validation-tool/blob/main/src/http/app.ts): `src/http/app.ts`
- [MCP Server](https://github.com/eneelkant/email-validation-tool/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [MCP Tools](https://github.com/eneelkant/email-validation-tool/blob/main/src/mcp/tools.ts): `src/mcp/tools.ts`
- [Website API](https://github.com/eneelkant/email-validation-tool/blob/main/src/http/website-api.ts): `src/http/website-api.ts`

### Validation

- [Syntax Checks](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/syntax.ts): `src/validators/syntax.ts`
- [Validation Orchestrator](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/orchestrator.ts): `src/validators/orchestrator.ts`
- [DNS Checks](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/dns.ts): `src/validators/dns.ts`
- [Provider Classification](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/disposable.ts): `src/validators/disposable.ts`
- [Free Providers](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/free-provider.ts): `src/validators/free-provider.ts`
- [Role Locals](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/role.ts): `src/validators/role.ts`
- [SMTP Diagnostics](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/smtp.ts): `src/validators/smtp.ts`
- [Catch-all Checks](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/catch-all.ts): `src/validators/catch-all.ts`
- [Result Normalization](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/result-normalize.ts): `src/validators/result-normalize.ts`
- [Result Schemas](https://github.com/eneelkant/email-validation-tool/blob/main/src/types/results.ts): `src/types/results.ts`

### Bulk Processing

- [Batch Validation](https://github.com/eneelkant/email-validation-tool/blob/main/src/processing/batch.ts): `src/processing/batch.ts`
- [CSV Jobs](https://github.com/eneelkant/email-validation-tool/blob/main/src/processing/csv.ts): `src/processing/csv.ts`

### State and Operations

- [SQLite Cache and Jobs](https://github.com/eneelkant/email-validation-tool/blob/main/src/database/db.ts): `src/database/db.ts`
- [Runtime Lifecycle](https://github.com/eneelkant/email-validation-tool/blob/main/src/runtime/lifecycle.ts): `src/runtime/lifecycle.ts`
- [Runtime Configuration](https://github.com/eneelkant/email-validation-tool/blob/main/src/config/env.ts): `src/config/env.ts`
- [Disposable Sync](https://github.com/eneelkant/email-validation-tool/blob/main/src/validators/disposable-sync.ts): `src/validators/disposable-sync.ts`
- [Bounded HTTP Reads](https://github.com/eneelkant/email-validation-tool/blob/main/src/utils/bounded-response.ts): `src/utils/bounded-response.ts`

### Website

- [Static Web UI](https://github.com/eneelkant/email-validation-tool/blob/main/public/js/app.js): `public/js/app.js`
- [Browser API Client](https://github.com/eneelkant/email-validation-tool/blob/main/public/js/verify.js): `public/js/verify.js`
- [Browser CSV](https://github.com/eneelkant/email-validation-tool/blob/main/public/js/csv.js): `public/js/csv.js`
- [Frontend Config](https://github.com/eneelkant/email-validation-tool/blob/main/public/js/config.js): `public/js/config.js`

### Other components

- **MCP Client**
- **Browser User**

## Connections

- MCP Client → MCP Server: uses (evidence: `README.md`)
- MCP Server → MCP Tools: registers tools (evidence: `src/mcp/server.ts`)
- HTTP Service → MCP Server: creates handler (evidence: `src/http/app.ts`)
- Browser User → Static Web UI: uses (evidence: `README.md`)
- Static Web UI → Browser API Client: calls (evidence: `public/js/app.js`)
- Static Web UI → Browser CSV: uses (evidence: `public/js/app.js`)
- Static Web UI → Frontend Config: reads config (evidence: `README.md`)
- Browser API Client → Website API: requests verification (evidence: `README.md`)
- HTTP Service → Website API: mounts (evidence: `src/http/app.ts`)
- Website API → Validation Orchestrator: validates (evidence: `src/http/website-api.ts`)
- Website API → Batch Validation: validates batches (evidence: `src/http/website-api.ts`)
- MCP Tools → Validation Orchestrator: validates (evidence: `src/mcp/tools.ts`)
- MCP Tools → Batch Validation: validates batches (evidence: `src/mcp/tools.ts`)
- MCP Tools → CSV Jobs: starts jobs (evidence: `src/mcp/tools.ts`)
- MCP Tools → SQLite Cache and Jobs: reads and writes (evidence: `src/mcp/tools.ts`)
- Validation Orchestrator → Syntax Checks: checks syntax
- Validation Orchestrator → DNS Checks: checks DNS (evidence: `README.md`)
- Validation Orchestrator → Provider Classification: classifies domains (evidence: `README.md`)
- Provider Classification → Free Providers: excludes overlaps (evidence: `src/validators/disposable-sync.ts`)
- Validation Orchestrator → Role Locals: checks role locals (evidence: `README.md`)
- Validation Orchestrator → SMTP Diagnostics: optionally checks (evidence: `README.md`)
- Validation Orchestrator → Catch-all Checks: optionally checks (evidence: `README.md`)
- Website API → Result Normalization: normalizes results (evidence: `src/http/website-api.ts`)
- MCP Tools → Result Normalization: normalizes results (evidence: `src/mcp/tools.ts`)
- Result Normalization → Result Schemas: shapes result (evidence: `src/database/db.ts`)
- Batch Validation → Validation Orchestrator: validates emails
- CSV Jobs → Batch Validation: processes batches (evidence: `README.md`)
- CSV Jobs → SQLite Cache and Jobs: tracks jobs
- HTTP Service → Runtime Lifecycle: checks readiness (evidence: `src/http/app.ts`)
- Runtime Lifecycle → SQLite Cache and Jobs: initializes (evidence: `src/runtime/lifecycle.ts`)
- Runtime Lifecycle → Provider Classification: loads dataset (evidence: `src/runtime/lifecycle.ts`)
- Runtime Lifecycle → Free Providers: loads dataset (evidence: `src/runtime/lifecycle.ts`)
- SQLite Cache and Jobs → Runtime Configuration: reads settings (evidence: `src/database/db.ts`)
- Disposable Sync → Bounded HTTP Reads: limits downloads (evidence: `src/validators/disposable-sync.ts`)
- Disposable Sync → Provider Classification: replaces dataset (evidence: `src/validators/disposable-sync.ts`)
- Disposable Sync → Free Providers: filters overlaps (evidence: `src/validators/disposable-sync.ts`)