How umuterturk/email-verifier works
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