# fbrusatti/active_merchant architecture

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

- Interactive diagram: https://gitdiagram.com/fbrusatti/active_merchant
- Repository: https://github.com/fbrusatti/active_merchant

## Overview

##### Primary Components
- Core Library – At the heart of the project is the “active_merchant” namespace, which aggregates the key utility modules (connection, error handling, parameter validation, and helper code). This serves as the backbone supporting all payment operations.
- Billing Module – This submodule contains the core billing logic such as credit card handling (credit card, formatting, and validation), response parsing, and request preparation.
- Integration Layer – Found in “lib/active_merchant/billing/integrations” this layer handles offsite payment integration, managing callbacks, notifications, and the redirection flows required by some providers.
- Generators – The “generators” directories (gateway and integration) indicate templating capabilities to scaffold new gateway integrations or extend existing functionality, suggesting an emphasis on extensibility.
- Test Infrastructure – Both “test/unit” and “test/remote” directories indicate a rigorous approach to unit testing and integration testing (including real remote gateway calls for validation).

##### Out Their Relationships and Data Flow
- Application Interface:
- The library is designed to integrate into a Rails or Ruby application via its init.rb and plugin mechanism.
- The client code obtains a gateway object (e.g., TrustCommerceGateway) and passes in a CreditCard instance and payment amount.
- Credit Card Processing:
- The Credit Card object (and related modules like expiry_date and verification via CVV classes) plays a central role in validating data before any payment is attempted.
- Gateway Adapter Communication:
- Once validated, the system uses the chosen gateway adapter from the “gateways” directory. Each adapter implements a common interface (derived from a shared Base class) to communicate with external payment APIs.
- Integration and Notification:
- For offsite payments, the integration modules handle helper routines for creating forms, handling notifications, and managing return/callback data flows.
- Utility / Support Functions:
- Supporting components such as logging, error handling, country codes, and other small utility classes reside in various “lib” subdirectories (e.g., lib/connection, lib/utils) and support the billing and gateway operations.

##### Architectural Patterns and Design Principles
- Modular Design / Plugin Architecture:
- The design promotes ease of extension. New gateways and integration points are added by implementing standardized templates—noted by the presence of generator scripts and templates.
- Abstraction via Common Interfaces:
- A shared abstract Gateway class and consistent request/response pattern across different adapters encapsulate varying external APIs behind a unified interface.
- Separation of Concerns:
- Distinct directories and modules isolate credit card processing, gateway communications, integration flows, and helper utilities.
- Test-Driven Development:
- A broad suite of both unit and remote tests ensures that payment flows and gateway interactions work reliably.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application/Rails Plugin Layer"
        RailsPlugin["init.rb"]:::plugin
    end

    subgraph "Active Merchant Library"
        CoreLibrary["Core Library"]:::core
        CoreMainFile["active_merchant.rb"]:::core
    end

    subgraph "Billing Components"
        BillingModule["Billing Module"]:::billing
        CreditCardValidator["Credit Card Validator"]:::billing
    end

    subgraph "Gateway Adapters"
        GatewaySubmodules["Gateway Submodules"]:::gateway
    end

    subgraph "Integration Layer"
        IntegrationLayer["Integration Layer"]:::integration
    end

    subgraph "Code Generators"
        Generators["Generators"]:::generators
        GeneratorsGateway["Gateway Generator"]:::generators
        GeneratorsIntegration["Integration Generator"]:::generators
    end

    subgraph "Test Infrastructure"
        UnitTests["Unit Tests"]:::test
        RemoteTests["Remote Tests"]:::test
    end

    ExternalGateways["External Payment Gateways"]:::external

    %% Data flow connections
    RailsPlugin -->|"initializes"| CoreLibrary
    CoreLibrary -->|"provides utilities for"| BillingModule
    BillingModule -->|"validates"| CreditCardValidator
    BillingModule -->|"routes to"| GatewaySubmodules
    BillingModule -->|"handles offsite"| IntegrationLayer
    GatewaySubmodules -->|"API calls"| ExternalGateways
    ExternalGateways -->|"responses"| GatewaySubmodules
    Generators -->|"scaffold"| GatewaySubmodules
    Generators -->|"scaffold"| IntegrationLayer
    UnitTests ---|"tests"| BillingModule
    UnitTests ---|"tests"| GatewaySubmodules
    UnitTests ---|"tests"| IntegrationLayer
    RemoteTests ---|"validates"| GatewaySubmodules

    %% Click Events
    click RailsPlugin "https://github.com/fbrusatti/active_merchant/blob/master/init.rb"
    click CoreLibrary "https://github.com/fbrusatti/active_merchant/tree/master/lib/active_merchant"
    click CoreMainFile "https://github.com/fbrusatti/active_merchant/blob/master/lib/active_merchant.rb"
    click BillingModule "https://github.com/fbrusatti/active_merchant/tree/master/lib/active_merchant/billing"
    click GatewaySubmodules "https://github.com/fbrusatti/active_merchant/tree/master/lib/active_merchant/billing/gateways"
    click IntegrationLayer "https://github.com/fbrusatti/active_merchant/tree/master/lib/active_merchant/billing/integrations"
    click Generators "https://github.com/fbrusatti/active_merchant/tree/master/generators"
    click GeneratorsGateway "https://github.com/fbrusatti/active_merchant/tree/master/generators/gateway"
    click GeneratorsIntegration "https://github.com/fbrusatti/active_merchant/tree/master/generators/integration"
    click UnitTests "https://github.com/fbrusatti/active_merchant/tree/master/test/unit"
    click RemoteTests "https://github.com/fbrusatti/active_merchant/tree/master/test/remote"

    %% Styling
    classDef plugin fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef billing fill:#afa,stroke:#333,stroke-width:2px;
    classDef gateway fill:#ffa,stroke:#333,stroke-width:2px;
    classDef integration fill:#aaf,stroke:#333,stroke-width:2px;
    classDef generators fill:#ffd,stroke:#333,stroke-width:2px;
    classDef test fill:#fda,stroke:#333,stroke-width:2px;
    classDef external fill:#faa,stroke:#333,stroke-width:2px;
```
