# apache/dubbo-erlang architecture

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

- Interactive diagram: https://gitdiagram.com/apache/dubbo-erlang
- Repository: https://github.com/apache/dubbo-erlang

## Overview

##### Project Type and Purpose
- dubboerl is a library/framework (not a user-facing app) that implements the Dubbo RPC protocol in Erlang.
- It provides:
- Core Erlang modules for protocol handling, registry, cluster, load-balancing, serialization (Hessian/JSON), connection pooling, filters, etc.
- A Java-based “erlanalysis” tool to generate Erlang bindings from Java interfaces.
- Sample consumer/provider apps in Java and Erlang.

##### File Structure
- Top-level directories:
- src/ (Erlang implementation modules)
- / (shared .hrl headers defining record types and macros)
- test/ (EUnit suites covering each core module)
- tools/erlanalysis (Java Maven project that parses Java interfaces and outputs Erlang code)
- samples/ (demo Java service, Erlang demo app)
- config_example, docs, rebar.config, README.md

##### Key Architectural Insights from the README
- dubboerl runs under Erlang/OTP, managed by a supervision tree (dubboerl_sup).
- It connects to a Zookeeper registry for service discovery.
- It speaks the Dubbo binary protocol over TCP, serializes payloads via Hessian or JSON.
- It uses extension points (behaviours) for protocol, cluster, registry, filters, load-balance.

##### Main Components
a. Erlanalysi s Tool (Java)
- Input: Java interfaces & JARs
- Output: Erlang module templates and .hrl files
- Relationship: Generates code that lives under your project’s app/src

b. Erlang Application (dubboerl OTP App)
- Supervision Tree: dubboerl_sup → children processes
- Core Modules (grouped by function):
- Configuration & Init: dubbo_config_util, dubboerl:init
- Registry & Discovery: dubbo_registry, dubbo_registry_zookeeper
- Protocol & Codec: dubbo_protocol, dubbo_codec, cotton_hessian
- Cluster & Load-Balance: dubbo_cluster, dubbo_loadbalance_random
- Consumer/Invoker: dubbo_reference_config, dubbo_invoker
- Provider/Worker: dubbo_provider_protocol, dubbo_provider_worker
- Connection Pool & Transport: dubbo_transport_pool_sup
- Extension & Filter Points: dubbo_extension, dubbo_filter
- Data Flow:
Erlang consumer call → invoker → transport pool → remote node → Hessian/JSON codec → provider → business code → reverse flow

c. External Systems
- Zookeeper Cluster (Registry Center)
- Java Dubbo Providers/Consumers (optional peers)

d. Sample Apps
- Java sample service (Spring/Maven) registers via ZK
- Erlang demo app (samples/dubboerl_demo) as consumer & provider, using generated code

##### Relationships & Interactions
- The erlanalysis tool → generates Erlang interface libs → included in the Erlang demo app
- At runtime, dubboerl:init() → starts OTP app → reads sys.config → spins up registry client → registers provider or subscribes consumer
- Consumer process → sends RPC request via TCP over Dubbo protocol → uses serialization → remote provider node → invokes implementation → returns response
- Registry client maintains subscriptions/registrations in ZK, handles node changes

##### Architectural Patterns & Principles
- OTP Supervision Tree (fault-tolerance)
- Behaviour-based extensions for protocol, registry, cluster, filters
- Process per connection / worker pool
- Separation of concerns: config, registry, protocol, serialization, transport, business code

##### Technologies & Frameworks
- Erlang/OTP (rebar3)
- Zookeeper (via dubbo_registry_zookeeper)
- Java/Maven for erlanalysis tool
- Hessian and JSON codecs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Tools & Code Generation
    subgraph "Tools & Code Generation"
        ERLAN["erlanalysis Tool (Java)"]:::tool
    end

    %% OTP Application
    subgraph "Erlang Application (dubboerl OTP App)"
        subgraph "Entry & Supervision"
            APP_SRC["dubboerl.app"]:::core
            APP["dubboerl"]:::core
            APP_APP["dubboerl_app"]:::core
            SUP["dubboerl_sup"]:::core
        end
        subgraph "Configuration & Init"
            CONFIG["dubbo_config_util"]:::core
        end
        subgraph "Registry & Discovery"
            REG["dubbo_registry"]:::core
            REG_ZK["dubbo_registry_zookeeper"]:::core
            REG_SUP["dubbo_registry_sup"]:::core
        end
        subgraph "Protocol & Codec"
            PROT["dubbo_protocol"]:::core
            CODEC["dubbo_codec"]:::core
            HESS["cotton_hessian"]:::core
            SER_H["dubbo_serializa_hessian"]:::core
            SER_J["dubbo_serializa_json"]:::core
        end
        subgraph "Cluster & LoadBalance"
            CLUST["dubbo_cluster"]:::core
            LB["dubbo_loadbalance_random"]:::core
        end
        subgraph "Consumer / Invoker"
            REF["dubbo_reference_config"]:::core
            INV["dubbo_invoker"]:::core
        end
        subgraph "Provider / Worker"
            PP["dubbo_provider_protocol"]:::core
            PW["dubbo_provider_worker"]:::core
            PWSUP["dubbo_provider_worker_sup"]:::core
        end
        subgraph "Connection Pool & Transport"
            TP["dubbo_transport_pool_sup"]:::core
        end
        subgraph "Extension & Filter Points"
            EXT["dubbo_extension"]:::core
            FIL["dubbo_filter"]:::core
        end
    end

    %% Sample Applications
    subgraph "Sample Applications"
        JAVAS["Java Sample Service"]:::business
        ERLDEMO["Erlang Demo App"]:::business
    end

    %% External Systems
    subgraph "External Systems"
        ZK["Zookeeper Cluster"]:::external
        JAVA["Java Dubbo Peers"]:::external
    end

    %% Relationships
    ERLAN -->|"generates code"| APP_SRC
    ERLAN -->|"outputs .hrl templates"| CONFIG

    APP_APP -->|"starts"| SUP
    SUP -->|"supervises"| CONFIG
    SUP -->|"supervises"| REG_SUP
    SUP -->|"supervises"| TP

    REG -->|"registers/subscribes"| ZK
    REG_ZK -->|"interacts with"| ZK

    INV -->|"uses protocol"| PROT
    PROT -->|"serializes via"| CODEC
    CODEC -->|"Hessian"| HESS
    CODEC -->|"JSON"| SER_J
    CODEC -->|"hands off payload"| TP

    INV -->|"sends RPC to"| TP
    TP -->|"delivers to"| PP
    PP -->|"spawns"| PWSUP
    PWSUP -->|"manages"| PW
    PW -->|"invokes business code in"| ERLDEMO

    JAVAS -->|"registers service"| ZK
    ERLDEMO -->|"calls init"| APP_APP

    %% Click Events
    click ERLAN "https://github.com/apache/dubbo-erlang/tree/master/tools/erlanalysis/"
    click APP_SRC "https://github.com/apache/dubbo-erlang/blob/master/src/dubboerl.app.src"
    click APP "https://github.com/apache/dubbo-erlang/blob/master/src/dubboerl.erl"
    click APP_APP "https://github.com/apache/dubbo-erlang/blob/master/src/dubboerl_app.erl"
    click SUP "https://github.com/apache/dubbo-erlang/blob/master/src/dubboerl_sup.erl"
    click CONFIG "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_config_util.erl"
    click REG "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_registry.erl"
    click REG_ZK "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_registry_zookeeper.erl"
    click REG_SUP "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_registry_sup.erl"
    click PROT "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_protocol.erl"
    click CODEC "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_codec.erl"
    click HESS "https://github.com/apache/dubbo-erlang/blob/master/src/cotton_hessian.erl"
    click SER_H "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_serializa_hessian.erl"
    click SER_J "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_serializa_json.erl"
    click CLUST "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_cluster.erl"
    click LB "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_loadbalance_random.erl"
    click REF "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_reference_config.erl"
    click INV "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_invoker.erl"
    click PP "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_provider_protocol.erl"
    click PW "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_provider_worker.erl"
    click PWSUP "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_provider_worker_sup.erl"
    click TP "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_transport_pool_sup.erl"
    click EXT "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_extension.erl"
    click FIL "https://github.com/apache/dubbo-erlang/blob/master/src/dubbo_filter.erl"
    click JAVAS "https://github.com/apache/dubbo-erlang/tree/master/samples/dubbo-sample-service/"
    click ERLDEMO "https://github.com/apache/dubbo-erlang/tree/master/samples/dubboerl_demo/apps/dubboerl_demo/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,color:#1B2631;
    classDef tool fill:#D2B4DE,stroke:#6C3483,color:#1B2631;
    classDef business fill:#A9DFBF,stroke:#196F3D,color:#1B2631;
    classDef external fill:#F5CBA7,stroke:#A04000,color:#1B2631;
```
