# afair/email_address architecture

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

- Interactive diagram: https://gitdiagram.com/afair/email_address
- Repository: https://github.com/afair/email_address

## Overview

This Ruby gem validates and transforms end-user email addresses; it is a library workflow rather than a standalone service. Callers use the `EmailAddress` helpers or construct an `Address`, which normalizes and splits input into local and host parts, then validates those parts according to configuration. Host validation may consult DNS and exchanger records. Address operations also provide canonical, base, digest-reference, redaction, munging, and SRS forms. Optional ActiveRecord integrations validate model fields and cast or serialize address values. The graph reflects the sampled runtime code and README capabilities; unsampled implementation details are represented only where the file tree supports them.

Main entry points: [`lib/email_address/address.rb`](https://github.com/afair/email_address/blob/master/lib/email_address/address.rb) (Address model), [`lib/email_address/host.rb`](https://github.com/afair/email_address/blob/master/lib/email_address/host.rb) (Host part), [`lib/email_address/active_record_validator.rb`](https://github.com/afair/email_address/blob/master/lib/email_address/active_record_validator.rb) (ActiveRecord validator), [`lib/email_address/config.rb`](https://github.com/afair/email_address/blob/master/lib/email_address/config.rb) (Rules and providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_email_api["EmailAddress API<br/>[email_address.rb]"]
end

subgraph group_address["Address Processing"]
  node_address["Address model<br/>[address.rb]"]
  node_rewriter["SRS rewriter<br/>[rewriter.rb]"]
  node_local["Local part<br/>[local.rb]"]
end

subgraph group_validation["Validation and DNS"]
  node_host["Host part<br/>[host.rb]"]
  node_config["Rules and providers<br/>[config.rb]"]
  node_messages["Error messages<br/>[messages.yaml]"]
  node_exchanger["MX exchanger lookup<br/>[exchanger.rb]"]
end

subgraph group_rails["Rails Integration"]
  node_ar_validator["ActiveRecord validator"]
  node_email_type["Email address type"]
  node_canonical_type["Canonical address type"]
end

node_caller(("Library caller"))
node_dns(("DNS resolver"))
node_smtp(("SMTP server"))
node_rails_app(("Rails application"))

node_caller -->|"calls helpers"| node_email_api
node_email_api -->|"constructs address"| node_address
node_address -->|"parses SRS"| node_rewriter
node_address -->|"parses local"| node_local
node_address -->|"parses host"| node_host
node_address -->|"validates local"| node_local
node_address -->|"validates host"| node_host
node_address -->|"loads error text"| node_config
node_host -->|"reads provider rules"| node_config
node_host -->|"gets exchangers"| node_exchanger
node_host -.->|"opens connection"| node_smtp
node_address -.->|"checks recipient"| node_smtp
node_exchanger -->|"queries MX records"| node_dns
node_host -->|"queries DNS"| node_dns
node_rails_app -->|"runs validation"| node_ar_validator
node_ar_validator -->|"validates value"| node_address
node_ar_validator -->|"gets error text"| node_config
node_rails_app -->|"casts and stores"| node_email_type
node_email_type -->|"normalizes value"| node_address
node_rails_app -->|"casts and stores"| node_canonical_type
node_canonical_type -->|"canonicalizes value"| node_address

click node_email_api "https://github.com/afair/email_address/blob/master/lib/email_address.rb"
click node_address "https://github.com/afair/email_address/blob/master/lib/email_address/address.rb"
click node_rewriter "https://github.com/afair/email_address/blob/master/lib/email_address/rewriter.rb"
click node_local "https://github.com/afair/email_address/blob/master/lib/email_address/local.rb"
click node_host "https://github.com/afair/email_address/blob/master/lib/email_address/host.rb"
click node_config "https://github.com/afair/email_address/blob/master/lib/email_address/config.rb"
click node_messages "https://github.com/afair/email_address/blob/master/lib/email_address/messages.yaml"
click node_exchanger "https://github.com/afair/email_address/blob/master/lib/email_address/exchanger.rb"
click node_ar_validator "https://github.com/afair/email_address/blob/master/lib/email_address/active_record_validator.rb"
click node_email_type "https://github.com/afair/email_address/blob/master/lib/email_address/email_address_type.rb"
click node_canonical_type "https://github.com/afair/email_address/blob/master/lib/email_address/canonical_email_address_type.rb"

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_email_api toneBlue
class node_address,node_rewriter,node_local toneAmber
class node_host,node_config,node_messages,node_exchanger,node_smtp toneMint
class node_ar_validator,node_email_type,node_canonical_type toneRose
class node_caller,node_dns,node_rails_app toneIndigo
```

## Components

### Public API

- [EmailAddress API](https://github.com/afair/email_address/blob/master/lib/email_address.rb): `lib/email_address.rb`

### Address Processing

- [Address model](https://github.com/afair/email_address/blob/master/lib/email_address/address.rb): `lib/email_address/address.rb`
- [SRS rewriter](https://github.com/afair/email_address/blob/master/lib/email_address/rewriter.rb): `lib/email_address/rewriter.rb`
- [Local part](https://github.com/afair/email_address/blob/master/lib/email_address/local.rb): `lib/email_address/local.rb`

### Validation and DNS

- [Host part](https://github.com/afair/email_address/blob/master/lib/email_address/host.rb): `lib/email_address/host.rb`
- [Rules and providers](https://github.com/afair/email_address/blob/master/lib/email_address/config.rb): `lib/email_address/config.rb`
- [Error messages](https://github.com/afair/email_address/blob/master/lib/email_address/messages.yaml): `lib/email_address/messages.yaml`
- [MX exchanger lookup](https://github.com/afair/email_address/blob/master/lib/email_address/exchanger.rb): `lib/email_address/exchanger.rb`

### Rails Integration

- [ActiveRecord validator](https://github.com/afair/email_address/blob/master/lib/email_address/active_record_validator.rb): `lib/email_address/active_record_validator.rb`
- [Email address type](https://github.com/afair/email_address/blob/master/lib/email_address/email_address_type.rb): `lib/email_address/email_address_type.rb`
- [Canonical address type](https://github.com/afair/email_address/blob/master/lib/email_address/canonical_email_address_type.rb): `lib/email_address/canonical_email_address_type.rb`

### Other components

- **Library caller**
- **DNS resolver**
- **SMTP server**
- **Rails application**

## Connections

- Library caller → EmailAddress API: calls helpers
- EmailAddress API → Address model: constructs address
- Address model → SRS rewriter: parses SRS
- Address model → Local part: parses local
- Address model → Host part: parses host
- Address model → Local part: validates local
- Address model → Host part: validates host
- Address model → Rules and providers: loads error text
- Host part → Rules and providers: reads provider rules
- Host part → MX exchanger lookup: gets exchangers
- Host part → SMTP server: opens connection
- Address model → SMTP server: checks recipient
- MX exchanger lookup → DNS resolver: queries MX records
- Host part → DNS resolver: queries DNS
- Rails application → ActiveRecord validator: runs validation
- ActiveRecord validator → Address model: validates value
- ActiveRecord validator → Rules and providers: gets error text
- Rails application → Email address type: casts and stores
- Email address type → Address model: normalizes value
- Rails application → Canonical address type: casts and stores
- Canonical address type → Address model: canonicalizes value