# umuterturk/email-verifier architecture

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

- Interactive diagram: https://gitdiagram.com/umuterturk/email-verifier
- Repository: https://github.com/umuterturk/email-verifier

## Overview

##### Project Type & Purpose
- This is a standalone, open-source, backend microservice written in Go.
- Purpose: expose a REST API for real-time email validation (syntax, domain/MX checks, disposable/role detection, alias normalization), optimized for batch workloads.
- Deployed via Docker Compose alongside Redis, Prometheus, and Grafana.

##### Top-Level Components
a. API Layer
- HTTP handlers (internal/api/handlers.go)
- OpenAPI spec (openapi.yaml)
- Static assets (docs/UI) served from /static (optional)
b. Service Layer
- EmailService, BatchValidationService, DomainValidationService (internal/service/*.go)
- Dependency-Injection interfaces for testability
c. Validation Layer (pkg/validator)
- SyntaxValidator, DomainValidator (with DNS lookups), DisposableValidator, RoleValidator, AliasDetector
d. Repository Layer
- Redis cache (pkg/cache/redis.go) for per-domain results
- Metrics adapter (pkg/monitoring)
- DNS resolver (pkg/validator/dns_resolver.go)

##### External Systems & Infrastructure
- Redis
- Caches domain-existence & MX lookups
- Prometheus
- Scrapes /metrics endpoint via HTTP for real-time metrics
- Grafana
- Dashboards built on Prometheus data (grafana-dashboard.json)
- DNS network
- External DNS servers for A/MX queries
- Clients
- REST clients (curl, mobile/web apps) call /api/validate and /api/validate/batch
- CI/CD (GitHub Actions) & Container Registry
- Build, test, publish Docker images (workflow YAML files)

##### Data-flow & Interactions
1. Client → HTTP REST API (/validate or /validate/batch)
2. API Layer
- Input validation → Service Layer call
3. Service Layer
- Batch requests: group emails by domain → call DomainValidationService once per domain
- EmailService: orchestrates syntax + domain + MX + disposable + role + alias checks
4. Validation Layer
- SyntaxValidator → returns format OK/fail
- DomainValidator:
– Check Redis cache
– If miss, perform DNS A/MX lookups → write back to Redis
- DisposableValidator & RoleValidator read lists from config files
- AliasDetector normalizes known-provider aliases
5. Repository Layer
- Redis I/O for cache
- MetricsAdapter logs counters/timers
6. API Layer → Response JSON
7. Service → /metrics endpoint → Prometheus
8. Prometheus → Grafana (visualization)

##### Architectural Patterns & Principles
- Layered architecture with strict separation of concerns
- Dependency Injection (interfaces.go) for mockability & test isolation
- Batch optimization → O(unique domains) domain checks
- Configuration-driven (config/*.txt, .env via fly.toml/docker-compose)
- Observability: metrics, CI/CD, containerization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["Clients (curl, mobile/web apps)"]:::external
    %% Main Service Container
    subgraph "Email Validator Service"
        direction TB
        %% API Layer
        subgraph "API Layer"
            direction TB
            Handlers["HTTP Handlers\n(internal/api/handlers.go)"]:::http
            OpenAPI["OpenAPI Spec\n(openapi.yaml)"]:::http
            Static["Static Assets\n(static/)"]:::http
        end
        %% Service Layer
        subgraph "Service Layer"
            direction TB
            EmailService["EmailService\n(internal/service/email_service.go)"]:::business
            BatchService["BatchValidationService\n(internal/service/batch_validation_service.go)"]:::business
            DomainService["DomainValidationService\n(internal/service/domain_validation_service.go)"]:::business
            Interfaces["Interfaces\n(internal/service/interfaces.go)"]:::business
            ServiceMetrics["Metrics Adapter\n(internal/service/metrics_adapter.go)"]:::observ
        end
        %% Validation Layer
        subgraph "Validation Layer"
            direction TB
            SyntaxVal["SyntaxValidator\n(pkg/validator/syntax_validator.go)"]:::business
            DomainVal["DomainValidator\n(pkg/validator/domain_validator.go)"]:::business
            DNSResolver["DNS Resolver\n(pkg/validator/dns_resolver.go)"]:::external
            DisposableVal["DisposableValidator\n(pkg/validator/disposable_validator.go)"]:::business
            RoleVal["RoleValidator\n(pkg/validator/role_validator.go)"]:::business
            AliasDet["AliasDetector\n(pkg/validator/alias_detector.go)"]:::business
            DomainCacheRW["Domain Cache\n(pkg/validator/domain_cache.go,\n pkg/validator/domain_reader.go)"]:::external
            EmailModel["Email Model\n(pkg/validator/email.go)"]:::business
        end
        %% Repository Layer
        subgraph "Repository Layer"
            direction TB
            RedisCache["Redis Cache\n(pkg/cache/redis.go)"]:::external
            PromMetrics["Prometheus Adapter\n(pkg/monitoring/metrics.go,\n pkg/monitoring/middleware.go)"]:::observ
        end
    end

    %% External Systems
    Redis["Redis"]:::external
    DNS["DNS Network"]:::external
    Prometheus["Prometheus"]:::observ
    Grafana["Grafana"]:::observ

    %% Data Flows
    Clients -->|HTTP Request| Handlers
    Handlers -->|"call Service"| EmailService
    Handlers -->|serves| OpenAPI
    Handlers -->|serves| Static

    EmailService -->|syntax check| SyntaxVal
    EmailService -->|batch optimize| BatchService
    BatchService -->|group domains| DomainService
    DomainService -->|domain validate| DomainVal

    DomainVal -->|check cache| RedisCache
    RedisCache -->|Redis GET/SET| Redis
    DomainVal -->|DNS Query| DNSResolver
    DNSResolver -->|A/MX Lookup| DNS
    DomainVal -->|cache result| RedisCache

    EmailService -->|disposable check| DisposableVal
    EmailService -->|role check| RoleVal
    EmailService -->|alias normalize| AliasDet

    %% Repository Metrics
    EmailService -->|metrics| PromMetrics
    Handlers -->|expose /metrics| PromMetrics
    PromMetrics -->|scrape /metrics| Prometheus
    Prometheus -->|visualize| Grafana

    %% Click Events
    click Handlers "https://github.com/umuterturk/email-verifier/blob/main/internal/api/handlers.go"
    click OpenAPI "https://github.com/umuterturk/email-verifier/blob/main/openapi.yaml"
    click Static "https://github.com/umuterturk/email-verifier/tree/main/static/"
    click EmailService "https://github.com/umuterturk/email-verifier/blob/main/internal/service/email_service.go"
    click BatchService "https://github.com/umuterturk/email-verifier/blob/main/internal/service/batch_validation_service.go"
    click DomainService "https://github.com/umuterturk/email-verifier/blob/main/internal/service/domain_validation_service.go"
    click Interfaces "https://github.com/umuterturk/email-verifier/blob/main/internal/service/interfaces.go"
    click ServiceMetrics "https://github.com/umuterturk/email-verifier/blob/main/internal/service/metrics_adapter.go"
    click SyntaxVal "https://github.com/umuterturk/email-verifier/blob/main/pkg/validator/syntax_validator.go"
    click DomainVal "https://github.com/umuterturk/email-verifier/blob/main/pkg/validator/domain_validator.go"
    click DNSResolver "https://github.com/umuterturk/email-verifier/blob/main/pkg/validator/dns_resolver.go"
    click DisposableVal "https://github.com/umuterturk/email-verifier/blob/main/pkg/validator/disposable_validator.go"
    click RoleVal "https://github.com/umuterturk/email-verifier/blob/main/pkg/validator/role_validator.go"
    click AliasDet "https://github.com/umuterturk/email-verifier/blob/main/pkg/validator/alias_detector.go"
    click DomainCacheRW "https://github.com/umuterturk/email-verifier/blob/main/pkg/validator/domain_cache.go"
    click RedisCache "https://github.com/umuterturk/email-verifier/blob/main/pkg/cache/redis.go"
    click PromMetrics "https://github.com/umuterturk/email-verifier/blob/main/pkg/monitoring/metrics.go"

    %% Styles
    classDef http fill:#add8e6,stroke:#333,stroke-width:1px
    classDef business fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef observ fill:#dda0dd,stroke:#333,stroke-width:1px
```
