# truemail-rb/truemail-rack architecture

> Architecture diagram of the GitHub repository truemail-rb/truemail-rack, 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/truemail-rb/truemail-rack
- Repository: https://github.com/truemail-rb/truemail-rack

## Overview

##### Project type and purpose
- This is a monolithic Rack-based web API (“truemail-rack”) written in Ruby.
- Purpose: expose a RESTful HTTP interface to the core Truemail gem for email validation (regex, DNS/MX, SMTP).
- No database. Uses environment variables for configuration and external services (DNS resolver, SMTP servers).

##### File structure
- Top‐level:
– config.ru – Rack entrypoint
– app/truemail_server – core application code
– config/system & initializers – configuration loader, types, environment setup
– spec – RSpec tests (requests, unit, system)
– CI & linting configurations (.circleci, .github, .rubocop, etc.)
- app/truemail_server:
– controllers/… – HTTP endpoints: healthcheck, version, validator, error handling
– router.rb – maps URL paths to controllers
– rack_cascade.rb – Rack middleware cascade (authentication, logging, error catching)
– services/… – AccessToken auth, EmailValidator orchestrator, Environment reader, Version
- No persistence layer.
- External dependencies appear only at runtime: DNS lookups, SMTP sessions.

##### README for additional insights
- Describes three main endpoints:
– GET /?email=… (with Authorization header)
– GET /version
– GET /healthcheck
- Lists environment variables controlling: tokens, regex patterns, MX/SMTP behavior, DNS servers, logging.
- Uses Thin as the Rack web server.

a. Main components:
1. API Client (curl, HTTP client, mobile/web UI)
2. HTTP Server (Thin)
3. Rack Middleware Cascade
4. Router
5. Controllers:
– ValidatorController
– VersionController
– HealthcheckController
– ErrorController
6. Services Layer:
– AccessTokenService (auth)
– EmailValidatorService (calls Truemail core)
– EnvironmentService (reads & validates ENV configs)
7. Truemail Core (external Ruby gem)
8. External Services: DNS resolver(s), SMTP servers
b. Data flow & interactions:
Client → Thin (TCP) → Rack Cascade (logging, auth via AccessTokenService) → Router
→ Controller logic (e.g. ValidatorController)
→ EnvironmentService (load config)
→ EmailValidatorService (invoke Truemail core)
→ Truemail core performs:
- Regex check
- DNS/MX lookup → DNS resolver
- SMTP session → SMTP server
← collects results
← returns JSON response
← Controller renders JSON → Rack → Thin → Client
c. Architectural patterns & principles:
- Separation of concerns: middleware vs routing vs controllers vs services
- Single‐responsibility: each service handles one aspect (auth, config, validation)
- External dependency inversion: core gem isolated behind service layer
- Stateless, config-via-ENV, no persistence
d. Key technologies & libraries:
- Ruby, Rack, Thin
- Truemail gem (email validation core)
- RSpec for tests
- CI: CircleCI, CodeClimate, linters (Rubocop, Yamllint, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% HTTP Layer
    subgraph "HTTP Layer"
        ConfigRU["config.ru\nThin (Rack Server)"]:::http
        Application["Rack Application"]:::http
    end

    %% Middleware
    subgraph "Middleware Cascade"
        Cascade["Rack Cascade\n(logging, auth, error handling)"]:::http
    end

    %% Routing
    Router["Router"]:::http

    %% Controllers
    subgraph "Controllers"
        BaseController["BaseController"]:::controllers
        ErrorController["ErrorController"]:::controllers
        HealthController["HealthcheckController"]:::controllers
        ValidatorController["ValidatorController"]:::controllers
        VersionController["VersionController"]:::controllers
    end

    %% Services
    subgraph "Services"
        AuthService["AccessTokenService\n(authentication)"]:::services
        EnvService["EnvironmentService\n(config reader)"]:::services
        ValidatorService["EmailValidatorService\n(core orchestration)"]:::services
        VersionDef["Application Version\ndefinition"]:::services
    end

    %% Core
    TruemailCore["Truemail Gem\n(email validation core)"]:::external

    %% External Systems
    subgraph "External Services"
        DNS["DNS Resolver"]:::external
        SMTP["SMTP Servers"]:::external
    end

    %% Flow
    Client[/"API Client"/] -->|"HTTP Request"| ConfigRU
    ConfigRU --> Application
    Application --> Cascade
    Cascade --> Router
    Router -->|"/healthcheck"| HealthController
    Router -->|"/version"| VersionController
    Router -->|"/?email"| ValidatorController
    Cascade --> ErrorController
    HealthController -->|uses| EnvService
    VersionController -->|reads| VersionDef
    VersionController -->|uses| EnvService
    ValidatorController -->|auth via| AuthService
    ValidatorController -->|load config| EnvService
    ValidatorController -->|validate email| ValidatorService
    ValidatorService -->|invoke| TruemailCore
    TruemailCore -->|DNS/MX lookup| DNS
    TruemailCore -->|SMTP session| SMTP
    TruemailCore --> ValidatorService
    ValidatorService --> ValidatorController
    HealthController --> Cascade
    VersionController --> Cascade
    ErrorController --> Cascade

    %% Click Events
    click ConfigRU "https://github.com/truemail-rb/truemail-rack/blob/master/config.ru"
    click Application "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/application.rb"
    click Cascade "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/rack_cascade.rb"
    click Router "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/router.rb"
    click BaseController "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/controllers/base.rb"
    click ErrorController "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/controllers/error/show.rb"
    click HealthController "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/controllers/healthcheck/show.rb"
    click ValidatorController "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/controllers/validator/show.rb"
    click VersionController "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/controllers/version/show.rb"
    click AuthService "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/services/access_token.rb"
    click ValidatorService "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/services/email_validator.rb"
    click EnvService "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/services/environment.rb"
    click VersionDef "https://github.com/truemail-rb/truemail-rack/blob/master/app/truemail_server/version.rb"
    click TruemailCore "https://github.com/truemail-rb/truemail-rack/blob/master/config/initializers/truemail.rb"
    click ConfigurationLoader "https://github.com/truemail-rb/truemail-rack/blob/master/config/loader.rb"
    click SystemTypes "https://github.com/truemail-rb/truemail-rack/blob/master/config/system/types.rb"
    click SystemConfig "https://github.com/truemail-rb/truemail-rack/blob/master/config/system/configuration.rb"
    click CommandLineParams "https://github.com/truemail-rb/truemail-rack/blob/master/config/system/command_line_params.rb"

    %% Styles
    classDef http fill:#E6E6FA,stroke:#9370DB,stroke-width:2px
    classDef controllers fill:#ADD8E6,stroke:#0000CD,stroke-width:2px
    classDef services fill:#90EE90,stroke:#228B22,stroke-width:2px
    classDef external fill:#D3D3D3,stroke:#696969,stroke-width:2px
```
