# dongxl123/butterfly architecture

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

- Interactive diagram: https://gitdiagram.com/dongxl123/butterfly
- Repository: https://github.com/dongxl123/butterfly

## Overview

##### Overall Project Type and Purpose
- The project is a library/framework intended for generating globally unique IDs in high-concurrency environments. It provides multiple implementations that cater to various deployment scenarios:
- Single machine id allocation using either database or ZooKeeper.
- Distributed mode with both Dubbo and Restful service implementations.
- The README outlines a few “发号器” issues (time rollback, machine id allocation/reclaim, and worker id limits) and describes innovative solutions, which are key to understanding the architecture.

##### File Structure
- The project is split into distinct modules:
- butterfly-allocator-db: Handles the DB-based worker id allocation mechanism.
- butterfly-allocator-zookeeper: Implements the ZooKeeper based solution.
- butterfly-allocator-distribute: Provides the distributed mode logic.
- butterfly-distribute: Contains server components using both Dubbo and Restful interfaces as well as the butterfly-api definitions for distributed access.
- butterfly-sample: Provides sample usages and tests for various allocation modes.
- butterfly-sequence: Contains the core ID generation logic (improved snowflake algorithm and sequence logic).
- The directories clearly separate implementations along the lines of allocation mechanisms and service interfacing. Notice the use of sub-packages like “worker”, “sequence”, “allocator”, “entity” and “config” that reveal an organized layered structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Distributed Service Layer"
        DS1["Butterfly Server (Dubbo)"]:::server
        DS2["Butterfly Server (Restful)"]:::server
    end

    subgraph "Core Engine Layer"
        C1["Butterfly Sequence"]:::core
    end

    subgraph "Allocator Modules"
        A1["DB Allocator"]:::allocator
        A2["ZooKeeper Allocator"]:::allocator
        A3["Distribute Allocator"]:::allocator
    end

    CLIENT["Client/Sample Application"]:::client
    API["Butterfly API"]:::api
    E1["Database (MySQL)"]:::external
    E2["ZooKeeper Cluster"]:::external

    CLIENT -->|"calls"| DS1
    CLIENT -->|"calls"| DS2

    DS1 -->|"exposes"| API
    DS2 -->|"exposes"| API

    API -->|"invokes"| C1

    C1 -->|"uses"| A1
    C1 -->|"uses"| A2
    C1 -->|"uses"| A3

    A1 -->|"updates"| E1
    A2 -->|"maintains"| E2

    classDef client fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef server fill:#66CCFF,stroke:#333,stroke-width:2px;
    classDef core fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef allocator fill:#99CC99,stroke:#333,stroke-width:2px;
    classDef api fill:#FFCCFF,stroke:#333,stroke-width:2px;
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:2px;

    click C1 "https://github.com/dongxl123/butterfly/tree/master/butterfly-sequence/"
    click A1 "https://github.com/dongxl123/butterfly/tree/master/butterfly-allocator/butterfly-allocator-db/"
    click A2 "https://github.com/dongxl123/butterfly/tree/master/butterfly-allocator/butterfly-allocator-zookeeper/"
    click A3 "https://github.com/dongxl123/butterfly/tree/master/butterfly-allocator/butterfly-allocator-distribute/"
    click API "https://github.com/dongxl123/butterfly/tree/master/butterfly-distribute/butterfly-api/"
    click DS1 "https://github.com/dongxl123/butterfly/tree/master/butterfly-distribute/butterfly-server-dubbo/"
    click DS2 "https://github.com/dongxl123/butterfly/tree/master/butterfly-distribute/butterfly-server-restful/"
    click CLIENT "https://github.com/dongxl123/butterfly/tree/master/butterfly-sample/"
```
