# dokeos/mailjet-gem architecture

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

- Interactive diagram: https://gitdiagram.com/dokeos/mailjet-gem
- Repository: https://github.com/dokeos/mailjet-gem

## Overview

##### Project Type and Purpose
- This is an open-source Ruby gem—a wrapper around Mailjet’s REST API—that provides:
- A generic HTTP client interface to Mailjet’s API endpoints, via resource classes under lib/mailjet/resources
- Rails & Rack integration for ActionMailer delivery and inbound event callbacks
- A code generator to bootstrap a Rails initializer

##### File Structure Analysis
Top-level files:
- mailjet.gemspec, Gemfile, Rakefile, README.md → Ruby gem boilerplate
- lib/mailjet.rb → gem entry point, loads submodules
- lib/mailjet/{configuration,connection,resource,exception,…}.rb → core modules
- lib/mailjet/resources/*.rb → one Ruby class per Mailjet API resource
- lib/mailjet/rack/endpoint.rb → Rack middleware for inbound callbacks
- lib/mailjet/mailer.rb & message_delivery.rb → ActionMailer adapters
- lib/generators/mailjet/… → Rails generator to create an initializer
- spec/… with VCR cassettes → automated HTTP-based tests

##### README Insights
- Describes authentication, configuration, versioning, supported API versions (v3, v3.1)
- Shows how users call Mailjet::Resource.create/.all/.find/.delete etc.
- Shows how to configure Rails ActionMailer delivery_method = :mailjet or :mailjet_api
- Demonstrates setting up Rack middleware to receive callback events

a. Main Components
- User Application Code (client scripts or Rails app)
- Mailjet Gem (modules below)
– Configuration module (holds API keys, default_from, endpoint)
– Connection module (builds HTTP requests, handles authentication, versioning)
– Resource layer (classes under mailjet/resources implement create, all, find, delete, custom actions)
– ActionMailer integration (mailer adapter + message_delivery bridge)
– Rack Endpoint middleware (Mailjet::Rack::Endpoint)
– Generator (Rails::Generators for initializer)
- External Dependencies
– Mailjet REST API (https://api.mailjet.com/v3/…)
– Rails ActionMailer (for mail delivery)
– Rack-compatible server/framework (Sinatra, Rails middleware stack)
– HTTP client library (e.g. net/http or Faraday)
- Test Harness
– VCR/cassettes and RSpec suite

b. Relationships & Data Flows
1. At runtime, client code calls Mailjet::<Resource> methods →
2. Configuration provides API keys and base URL →
3. Connection builds and sends HTTP(S) request to Mailjet API →
4. API responds with JSON/XML →
5. Connection parses response and hands back a Resource object or collection →
6. In Rails context, ActionMailer invokes Mailjet::Mailer or Mailjet::MessageDelivery to send email via the API instead of SMTP →
7. For inbound events, HTTP requests from Mailjet’s webhooks hit the Rack::Endpoint middleware →
8. Middleware yields params to user’s block in Rails application

c. Architectural Patterns & Principles
- Facade pattern: Mailjet module hides low-level HTTP details
- ActiveResource-like resource classes: one class per endpoint, uniform .create/.all/.find/.delete API
- Dependency injection via Configuration object
- Rack middleware pattern for callbacks
- Generator pattern for Rails integration

d. Key Technologies & Libraries
- Ruby 2.2+
- RSpec & VCR for testing
- Rails generators, ActionMailer for delivery integration
- Rack interface for inbound events
- HTTP client (standard library or Faraday/net-http)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Application
    App["User Application"]:::external

    %% Mailjet Gem Modules
    subgraph "Mailjet Gem"
        Entry["lib/mailjet.rb"]:::internal
        Config["Configuration"]:::internal
        Conn["Connection"]:::internal
        Exception["Exception Handling"]:::internal
        CollProxy["Collection Proxy"]:::internal
        ResBase["Resource Base Class"]:::internal
        ResLayer["API Resources"]:::internal
        Mailer["ActionMailer Adapter"]:::adapter
        MsgDeliv["Message Delivery Bridge"]:::adapter
        RackEP["Rack Endpoint Middleware"]:::middleware
        Generator["Initializer Generator"]:::generator
        Template["Generator Template"]:::generator
    end

    %% External Systems
    MJAPI["Mailjet REST API"]:::external
    RailsAM["Rails ActionMailer"]:::external
    RackServer["Rack Server / Framework"]:::external

    %% Test Harness
    Test["RSpec & VCR Tests"]:::test

    %% Data Flows
    App -->|loads| Entry
    Entry --> Config
    Entry --> Conn
    Entry --> ResLayer
    Entry --> Exception
    Entry --> CollProxy
    Entry --> ResBase

    App -->|calls Resource methods| ResLayer
    ResLayer -->|uses| Conn
    Conn -->|HTTP request| MJAPI
    MJAPI -->|HTTP response| Conn
    Conn -->|returns data| ResLayer
    ResLayer -->|returns objects| App

    RailsAM -->|invokes| Mailer
    Mailer -->|uses| Conn
    Mailer -->|sends via| MsgDeliv
    MsgDeliv -->|uses| Conn

    RackServer -->|routes webhook| RackEP
    RackEP -->|yields params| App

    Generator -->|generates initializer from| Template

    Test -->|tests| Conn
    Test -->|tests| ResLayer

    %% Click Events
    click Entry "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet.rb"
    click Config "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/configuration.rb"
    click Conn "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/connection.rb"
    click Exception "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/exception/errors.rb"
    click CollProxy "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/collection_proxy.rb"
    click ResBase "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/resource.rb"
    click ResLayer "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/resources/*.rb"
    click Mailer "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/mailer.rb"
    click MsgDeliv "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/message_delivery.rb"
    click RackEP "https://github.com/dokeos/mailjet-gem/blob/master/lib/mailjet/rack/endpoint.rb"
    click Generator "https://github.com/dokeos/mailjet-gem/blob/master/lib/generators/mailjet/initializer_generator.rb"
    click Template "https://github.com/dokeos/mailjet-gem/blob/master/lib/generators/mailjet/templates/mailjet.rb.erb"

    %% Styles
    classDef internal fill:#D6EFFF,stroke:#1E90FF
    classDef external fill:#FFF4CE,stroke:#FFAA33
    classDef adapter fill:#E6FFED,stroke:#2ECC71
    classDef middleware fill:#F0E6FF,stroke:#8E44AD
    classDef generator fill:#FFFAE6,stroke:#F1C40F
    classDef test fill:#F2F2F2,stroke:#CCCCCC
```
