# openware/opendax architecture

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

- Interactive diagram: https://gitdiagram.com/openware/opendax
- Repository: https://github.com/openware/opendax

## Overview

##### Project type and purpose
- OpenDAX is a Ruby-based CLI/toolkit that orchestrates deployment of a full-stack, cloud-native, multi-service cryptocurrency exchange platform.
- It generates configuration and Docker Compose files from ERB templates, manages infrastructure provisioning via Terraform, and controls service lifecycle via Rake tasks.

##### Key architectural characteristics
- Microservices deployed as Docker containers
- Configuration-as-code using `config/*.yml` + ERB templates in `templates/`
- Secrets management via Vault
- Infrastructure provisioning with Terraform
- Service orchestration with Docker Compose & Rake

##### Main components
A. Developer/Operator Environment
- CLI tool (`bin/*.sh`, `lib/opendax/*`)
- Configuration source (`config/app.yml`, `templates/`)
- Rake tasks and Terraform code (`Rakefile`, `terraform/*.tf`, `lib/tasks`)
B. Rendering & Provisioning Layer
- ERB template renderer (lib/opendax/renderer.rb)
- `docker-compose` files generator (`templates/compose/*.yml.erb` → `compose/*.yaml`)
- `rake terraform:apply` provisioning
C. Docker Compose Stack
1. Proxy
– Traefik edge router
– Routes external HTTP(s) to internal services
2. API Gateway & Auth
– Ambassador API gateway
– Barong (authentication & KYC service)
3. Exchange Core
– Peatio (matching engine, order book, trade executor)
– Ranger daemons (cron_job, deposit, withdraw, upstream)
4. Backend Infra
– Vault (secrets management)
– MySQL (persistent data)
– Redis (caching, sessions)
– RabbitMQ (message queue between daemons)
5. Crypto Nodes (optional)
– parity, bitcoind, litecoind containers
6. Frontend Services
– Base frontend app (static assets served via proxy)
– Tower admin panel
7. Monitoring & Metrics (optional)
– cAdvisor, Prometheus node_exporter
8. Setup Hooks
– Database migrations, seeding (setup container)

##### Relationships and data flow
- External user → Traefik → Ambassador gateway
- Ambassador → Barong for authentication → issues JWT/CSRF
- Authenticated requests → Peatio REST/gRPC API → trades go to matching engine
- Peatio publishes events → RabbitMQ → Ranger daemons handle deposits/withdrawals
- Daemons interact with crypto-node containers for blockchain operations
- Vault issues tokens to components → components request secrets at runtime
- Frontend/Tower call Ambassador for API requests
- Monitoring tools scrape metrics from containers

##### Architectural patterns & design principles
- Microservices with single responsibility per container
- Infrastructure as code (Terraform + Docker Compose)
- Template-driven configuration (ERB → YAML)
- Secrets isolation via Vault policies per component
- Clear separation between rendering/orchestration and runtime

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Operator Environment
    subgraph "Operator Environment"
        direction TB
        CLI["CLI Toolkit (bin/*.sh)"]:::blue
        ConfigSrc["Configuration Source (config/*.yml)"]:::blue
        RakeTF["Rake Tasks & Terraform (Rakefile, terraform/*.tf)"]:::blue
    end

    %% Rendering & Provisioning
    subgraph "Rendering & Provisioning"
        direction TB
        Renderer["ERB Template Renderer (lib/opendax/renderer.rb)"]:::blue
        ComposeGen["Compose Files Generator (templates/compose → compose/)"]:::blue
        TerraformApply["rake terraform:apply"]:::blue
    end

    %% Runtime Stack
    subgraph "Docker Compose Runtime Stack"
        direction TB
        subgraph "Proxy & Gateway"
            direction TB
            Traefik["Traefik Proxy"]:::green
            Ambassador["Ambassador API Gateway"]:::green
        end
        subgraph "Authentication"
            direction TB
            Barong["Barong Auth Service"]:::orange
        end
        subgraph "Exchange Core"
            direction TB
            Peatio["Peatio Matching Engine"]:::orange
            RabbitMQ["RabbitMQ MQ"]:::yellow
            subgraph "Ranger Daemons"
                direction TB
                Daemons["Ranger Daemons"]:::orange
            end
        end
        subgraph "Backend Infra"
            direction TB
            Vault["Vault Secrets"]:::yellow
            MySQL["MySQL DB"]:::yellow
            Redis["Redis Cache"]:::yellow
        end
        subgraph "Crypto Nodes (optional)"
            direction TB
            Crypto["Parity/bitcoind/litecoind"]:::purple
        end
        subgraph "Frontends"
            direction TB
            Frontend["Base Frontend App"]:::white
            Tower["Tower Admin Panel"]:::white
        end
        subgraph "Monitoring (optional)"
            direction TB
            Mon["cAdvisor/node_exporter"]:::grey
        end
        Setup["Setup Hooks (migrations & seeds)"]:::blue
    end

    %% Operator to Rendering
    CLI --> Renderer
    ConfigSrc --> Renderer
    RakeTF --> Renderer

    %% Rendering to Runtime
    ComposeGen --> Traefik
    ComposeGen --> Ambassador
    ComposeGen --> Barong
    ComposeGen --> Peatio
    ComposeGen --> Daemons
    ComposeGen --> Vault
    ComposeGen --> MySQL
    ComposeGen --> Redis
    ComposeGen --> RabbitMQ
    ComposeGen --> Crypto
    ComposeGen --> Frontend
    ComposeGen --> Tower
    ComposeGen --> Mon
    TerraformApply -.->|"provisions hosts"| Traefik

    %% Data Flow
    UserExternal([External User]):::white -->|"HTTP(s)"| Traefik
    Traefik -->|"HTTP(s)"| Ambassador
    Ambassador -->|"auth request"| Barong
    Barong -->|"JWT/CSRF"| Ambassador
    Ambassador -->|"gRPC/REST"| Peatio
    Peatio -->|"events"| RabbitMQ
    RabbitMQ -->|"jobs"| Daemons
    Daemons -->|"blockchain ops"| Crypto
    Peatio -->|"secret fetch"| Vault
    Ambassador -->|"secret fetch"| Vault
    Daemons -->|"secret fetch"| Vault
    Frontend -->|"API calls"| Ambassador
    Tower -->|"API calls"| Ambassador
    Mon -->|"scrape metrics"| Traefik
    Mon -->|"scrape metrics"| Ambassador
    Mon -->|"scrape metrics"| Barong
    Mon -->|"scrape metrics"| Peatio
    Mon -->|"scrape metrics"| RabbitMQ
    Mon -->|"scrape metrics"| MySQL
    Mon -->|"scrape metrics"| Redis
    Mon -->|"scrape metrics"| Daemons
    Mon -->|"scrape metrics"| Crypto

    %% Click Events
    click CLI "https://github.com/openware/opendax/blob/2-6-stable/bin/start.sh"
    click CLI "https://github.com/openware/opendax/blob/2-6-stable/bin/install.sh"
    click CLI "https://github.com/openware/opendax/blob/2-6-stable/bin/set-env.sh"
    click CLI "https://github.com/openware/opendax/blob/2-6-stable/bin/quick-test.sh"
    click Renderer "https://github.com/openware/opendax/blob/2-6-stable/lib/opendax/renderer.rb"
    click Renderer "https://github.com/openware/opendax/blob/2-6-stable/lib/opendax/vault.rb"
    click Renderer "https://github.com/openware/opendax/blob/2-6-stable/lib/opendax/payload.rb"
    click RakeTF "https://github.com/openware/opendax/tree/2-6-stable/Rakefile"
    click RakeTF "https://github.com/openware/opendax/blob/2-6-stable/lib/tasks/render.rake"
    click RakeTF "https://github.com/openware/opendax/blob/2-6-stable/lib/tasks/docker.rake"
    click RakeTF "https://github.com/openware/opendax/blob/2-6-stable/lib/tasks/terraform.rake"
    click RakeTF "https://github.com/openware/opendax/blob/2-6-stable/lib/tasks/service.rake"
    click RakeTF "https://github.com/openware/opendax/blob/2-6-stable/lib/tasks/vault.rake"
    click ConfigSrc "https://github.com/openware/opendax/blob/2-6-stable/config/app.yml"
    click ConfigSrc "https://github.com/openware/opendax/blob/2-6-stable/config/utils.yml"
    click ConfigSrc "https://github.com/openware/opendax/tree/2-6-stable/config/"
    click ComposeGen "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/*.yml.erb"
    click ComposeGen "https://github.com/openware/opendax/tree/2-6-stable/templates/config/"
    click ComposeGen "https://github.com/openware/opendax/blob/2-6-stable/templates/terraform/terraform.tfvars.erb"
    click ComposeGen "https://github.com/openware/opendax/blob/2-6-stable/compose/*.yaml"
    click RakeTF "https://github.com/openware/opendax/blob/2-6-stable/terraform/main.tf"
    click RakeTF "https://github.com/openware/opendax/blob/2-6-stable/terraform/variables.tf"
    click Traefik "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/proxy.yaml.erb"
    click Traefik "https://github.com/openware/opendax/blob/2-6-stable/compose/proxy.yaml"
    click Ambassador "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/gateway.yaml.erb"
    click Ambassador "https://github.com/openware/opendax/blob/2-6-stable/compose/gateway.yaml"
    click Ambassador "https://github.com/openware/opendax/tree/2-6-stable/config/gateway/"
    click Barong "https://github.com/openware/opendax/tree/2-6-stable/templates/config/barong/"
    click Barong "https://github.com/openware/opendax/blob/2-6-stable/config/barong/barong.yml"
    click Peatio "https://github.com/openware/opendax/tree/2-6-stable/templates/config/peatio/"
    click Peatio "https://github.com/openware/opendax/tree/2-6-stable/config/peatio/"
    click Daemons "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/daemons.yaml.erb"
    click Daemons "https://github.com/openware/opendax/blob/2-6-stable/compose/daemons.yaml"
    click Vault "https://github.com/openware/opendax/blob/2-6-stable/lib/opendax/vault.rb"
    click Vault "https://github.com/openware/opendax/tree/2-6-stable/templates/config/vault/"
    click MySQL "https://github.com/openware/opendax/blob/2-6-stable/config/mysql/innodb.cnf"
    click MySQL "https://github.com/openware/opendax/tree/2-6-stable/data/mysql/"
    click Redis "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/backend.yaml.erb"
    click Redis "https://github.com/openware/opendax/blob/2-6-stable/compose/backend.yaml"
    click RabbitMQ "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/backend.yaml.erb"
    click RabbitMQ "https://github.com/openware/opendax/blob/2-6-stable/compose/backend.yaml"
    click Crypto "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/cryptonodes.yaml.erb"
    click Crypto "https://github.com/openware/opendax/blob/2-6-stable/compose/cryptonodes.yaml"
    click Crypto "https://github.com/openware/opendax/blob/2-6-stable/templates/config/bitcoin.conf.erb"
    click Crypto "https://github.com/openware/opendax/blob/2-6-stable/templates/config/litecoin.conf.erb"
    click Frontend "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/frontend.yaml.erb"
    click Frontend "https://github.com/openware/opendax/blob/2-6-stable/compose/frontend.yaml"
    click Frontend "https://github.com/openware/opendax/tree/2-6-stable/config/frontend/"
    click Tower "https://github.com/openware/opendax/blob/2-6-stable/templates/config/frontend/tower.js.erb"
    click Tower "https://github.com/openware/opendax/blob/2-6-stable/config/frontend/tower.js"
    click Mon "https://github.com/openware/opendax/blob/2-6-stable/templates/compose/monitoring.yaml.erb"
    click Mon "https://github.com/openware/opendax/blob/2-6-stable/compose/monitoring.yaml"
    click Setup "https://github.com/openware/opendax/blob/2-6-stable/lib/tasks/db.rake"
    click Setup "https://github.com/openware/opendax/tree/2-6-stable/templates/config/peatio/seed/"
    
    %% Styles
    classDef blue fill:#d0e7ff,stroke:#004085
    classDef green fill:#d4edda,stroke:#155724
    classDef orange fill:#fff3cd,stroke:#856404
    classDef yellow fill:#fff3cd,stroke:#856404
    classDef purple fill:#e2e3e5,stroke:#6c757d
    classDef grey fill:#f8f9fa,stroke:#6c757d
    classDef white fill:#ffffff,stroke:#000000
```
