# juspay/decision-engine architecture

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

- Interactive diagram: https://gitdiagram.com/juspay/decision-engine
- Repository: https://github.com/juspay/decision-engine

## Overview

##### Main Components
- Decision Engine Core – This is the entry point for payment routing. It handles eligibility checks, rule-based ordering, dynamic gateway ordering, and downtime detection.
- Payment Routing Modules – These are implemented in separate crates (for example, the “dynamo” and “open-router” crates). They encapsulate specific business logic such as:
– Eligibility checks
– Contract/routing rules evaluation (seen in “contract_routing” modules)
– Health checks (modules in “health_check”)
– Success rate handling and elimination logic for dynamic gateway ordering
- Authentication & Security – Components responsible for authentication, hashing, secrets management, and encryption (spread across “src/authentication”, “src/secrets”, and several crypto-related directories in the “open-router” crate).
- Auxiliary Services – Additional supporting components such as logging, ephemeral storage (for temporary data like success rate calculations), and metrics gathering.
- Simulator & Tester – A separate crate (“simulator”) provides a way to mimic transaction flows, file storage (including S3 and local file system options), and health/simulation endpoints to test the engine.
- Configuration and Orchestration – The configuration files (under “config” and the various “config.example.toml”, “development.toml”, etc.) manage environment-specific settings and deployment parameters. The project also provides Docker and GitHub workflows, so consider a containerized deployment aspect.

##### Relationships and Interactions
- Validate and authenticate the request.
- Evaluate eligibility rules based on incoming payment information.
- Process routing decisions by consulting rule-based ordering modules as well as real-time success rate metrics.
- Perform health checks and dynamically reorder gateways based on downtime detection.
- Module Interactions – Emphasize how the “dynamo” crate might interact with the “open-router” as part of the decision logic. For instance, authentication modules feed data into routing decisions, and the crypto modules (in “open-router/src/crypto”) help secure secrets and data integrity.
- External Dependencies – Although not explicitly shown in code here, note that the system may interface with external PCI-compliant vaults, databases (possibly using Diesel in “open-router”), and caching layers (with Redis in “open-router/src/redis”).

##### Architectural Patterns & Design Principles
- Modularity via Rust Crates – The repository is split into multiple crates (dynamo, open-router, procesmo, simulator) which not only separate concerns but also allow for individual testing and provisioning.
- Layered Approach – The system separates concerns into:
– API and request handling (entry points and routing)
– Core decision logic (eligibility, rules, dynamic ordering)
– Infrastructure services (authentication, encryption, logging, health monitoring, caching)
- Use of Microservice-like Separation – Although all modules reside within one repository, they can be visualized as separate services (especially with Docker container deployments) communicating through clearly defined interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Services
    A["Decision Engine Core"]:::core

    %% Payment Routing Modules
    subgraph "Payment Routing Modules"
        B["Eligibility & Contract Routing"]:::module
        C["Dynamic Gateway Ordering & Elimination Logic"]:::module
        D["Success Rate Handling"]:::module
        E["Health Checks"]:::module
    end

    %% Infrastructure & Security
    subgraph "Infrastructure & Security"
        F["Authentication & Security"]:::infra
        G["Crypto & Secrets Management"]:::infra
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        H["Logging"]:::aux
        I["Ephemeral Storage (Success Rate)"]:::aux
        J["Metrics Gathering"]:::aux
    end

    %% External Interfaces
    subgraph "External Interfaces"
        K["Simulator & Tester"]:::external
        L["Configuration & Orchestration"]:::external
        M["Documentation & API Reference"]:::external
        N["Dockerfile (Project Root)"]:::external
        O["Dockerfile (Open-Router)"]:::external
    end

    %% Connections between Core and Payment Routing Modules
    A -->|"routes to"| B
    A -->|"routes to"| C
    A -->|"routes to"| E

    %% Payment Routing internal flows
    C -->|"utilizes"| D

    %% Interactions with Infrastructure
    B -->|"requires"| F
    C -->|"requires"| F
    E -->|"requires"| F
    F -->|"secures"| G

    %% Auxiliary services connections
    A -->|"logs"| H
    B -->|"logs"| H
    C -->|"logs"| H
    E -->|"logs"| H

    A ---|"metrics"| J
    B ---|"metrics"| J
    C ---|"metrics"| J
    E ---|"metrics"| J

    B ---|"ephemeral data"| I
    C ---|"ephemeral data"| I

    %% External Interfaces interactions
    K -->|"simulates"| A
    L -->|"configures"| A
    L -->|"configures"| F
    L -->|"configures"| B
    L -->|"configures"| C
    L -->|"configures"| E
    M ---|"documents"| A

    L -->|"includes"| N
    L -->|"includes"| O

    %% Click Events
    click A "https://github.com/juspay/decision-engine/blob/main/crates/dynamo/src/bin/dynamo.rs"
    click B "https://github.com/juspay/decision-engine/blob/main/crates/dynamo/src/contract_routing.rs"
    click C "https://github.com/juspay/decision-engine/blob/main/crates/dynamo/src/elimination.rs"
    click D "https://github.com/juspay/decision-engine/blob/main/crates/dynamo/src/success_rate.rs"
    click E "https://github.com/juspay/decision-engine/blob/main/crates/dynamo/src/health_check.rs"
    click F "https://github.com/juspay/decision-engine/tree/main/crates/dynamo/src/authentication/"
    click G "https://github.com/juspay/decision-engine/tree/main/crates/open-router/src/crypto/"
    click H "https://github.com/juspay/decision-engine/tree/main/crates/dynamo/src/logger/"
    click I "https://github.com/juspay/decision-engine/tree/main/crates/dynamo/src/ephemeral_store/success_rate/"
    click J "https://github.com/juspay/decision-engine/blob/main/crates/dynamo/src/metrics.rs"
    click K "https://github.com/juspay/decision-engine/blob/main/crates/simulator/src/bin/simulator.rs"
    click L "https://github.com/juspay/decision-engine/tree/main/config/"
    click M "https://github.com/juspay/decision-engine/tree/main/docs/"
    click N "https://github.com/juspay/decision-engine/tree/main/Dockerfile"
    click O "https://github.com/juspay/decision-engine/tree/main/crates/open-router/Dockerfile"

    %% Styles
    classDef core fill:#a8dba8,stroke:#457b9d,stroke-width:2px;
    classDef module fill:#cce5ff,stroke:#3a5fcd,stroke-width:2px;
    classDef infra fill:#f9d1d1,stroke:#d1495b,stroke-width:2px;
    classDef aux fill:#fff2cc,stroke:#ffd700,stroke-width:2px;
    classDef external fill:#e8e8e8,stroke:#9e9e9e,stroke-width:2px;
```
