# buraksezer/consistent architecture

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

- Interactive diagram: https://gitdiagram.com/buraksezer/consistent
- Repository: https://github.com/buraksezer/consistent

## Overview

##### Project type and purpose
- This is a Go library (not a full-stack app) implementing a consistent-hashing algorithm with bounded loads.
- It exposes a core package “consistent” which clients import to distribute keys across a dynamic set of members.

##### File structure analysis
- Top-level
- consistent.go           → core algorithm, types (Config, Member interface, ring management)
- consistent_test.go      → unit tests validating algorithm correctness
- go.mod                  → module declaration and external dependencies
- LICENSE, README.md      → project metadata
- .github/workflows/*.yml → CI configurations (tests, lint, CodeQL)
- .travis.yml             → legacy CI config
- _examples folder
- Several small Go programs showing how to configure and use the library (e.g., load_distribution.go, relocation_percentage.go).
- No frontend/backend split or database—this is a small standalone library.

##### Key architecture elements
a. Core components
– Config object: holds PartitionCount, ReplicationFactor, Load, Hasher
– Hasher interface: abstraction over hash function implementations (e.g., xxhash)
– Member interface: entities to which partitions are assigned
– Ring manager: builds a ring of replicated member-nodes, computes average loads, and distributes partitions
– Locator functions: LocateKey, GetClosestN – resolve a key to the owning Member(s)
b. Support components
– Examples: sample Go programs demonstrating usage
– Tests: exercise core logic for correctness and performance
– CI pipelines: enforce code quality, run tests, static analysis

##### Relationships and data-flow
- Client code (examples or external consumers) → constructs a Config + implements Hasher & Member → calls New() to get a Consistent instance.
- Consistent instance:
1) On Add(member): Hash the member’s name → place multiple replicas on the ring → recalculate average load → assign partitions.
2) On LocateKey(key): Hash key → mod by PartitionCount → lookup partition owner in ring → return Member.
3) On GetClosestN(key, n): similar but returns top-n owners.
- No external databases or network calls—all in-process memory, except when the client persists data.

##### Architectural patterns and principles
- Strategy pattern: pluggable Hasher implementations
- Interface segregation: Member vs. Hasher vs. Config
- Algorithm encapsulation: ring and partition distribution hidden behind simple API
- Zero-GC lookups (minimal allocations on LocateKey)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Examples
    subgraph "User Code (Examples)" 
        direction TB
        EX1["_examples/add_and_list.go"]:::external
        EX2["_examples/load_distribution.go"]:::external
        EX3["_examples/relocation_percentage.go"]:::external
        EX4["_examples/sample.go"]:::external
    end

    %% Core Library
    subgraph "Core Library (consistent)" 
        direction TB
        Config["consistent.Config"]:::api
        Hasher["Hasher (interface)"]:::api
        Member["Member (interface)"]:::api
        New["New(Config) → Consistent"]:::api

        subgraph "Ring Manager" 
            direction TB
            Replica["Replica placement"]:::internal
            LoadCalc["Load calculator"]:::internal
            Distributor["Partition distributor"]:::internal
        end

        Locator1["LocateKey(key)"]:::api
        LocatorN["GetClosestN(key, n)"]:::api
    end

    %% Tests
    subgraph "Tests" 
        direction TB
        Test["consistent_test.go"]:::test
    end

    %% CI Pipelines
    subgraph "CI Pipelines"
        direction TB
        CI1[".github/workflows/tests.yml"]:::ci
        CI2[".github/workflows/codeql-analysis.yml"]:::ci
        CI3[".travis.yml"]:::ci
    end

    %% Metadata
    subgraph "Project Metadata & Module"
        direction TB
        Mod["go.mod"]:::metadata
        Meta1["README.md"]:::metadata
        Meta2["LICENSE"]:::metadata
    end

    %% Relationships
    EX1 -->|uses| Config
    EX1 -->|implements| Hasher
    EX1 -->|implements| Member
    EX2 -->|uses| Config
    EX2 -->|implements| Hasher
    EX2 -->|implements| Member
    EX3 -->|uses| Config
    EX3 -->|implements| Hasher
    EX3 -->|implements| Member
    EX4 -->|uses| Config
    EX4 -->|implements| Hasher
    EX4 -->|implements| Member

    Config -->|"New()"| New
    Hasher -->|"injected into"| New
    Member -->|"injected into"| New
    New -->|"builds"| Replica
    New -->|"builds"| LoadCalc
    New -->|"builds"| Distributor
    Replica -->|"populates ring"| Locator1
    LoadCalc -->|"calculates avg load"| Distributor
    Distributor -->|"assigns partitions"| Locator1
    Distributor -->|"assigns partitions"| LocatorN
    Locator1 -->|"returns Member"| EX1
    Locator1 -->|"returns Member"| EX2
    LocatorN -->|"returns Member list"| EX3
    LocatorN -->|"returns Member list"| EX4

    Test -.->|exercises| Config
    Test -.->|exercises| Replica
    Test -.->|exercises| Locator1

    CI1 -.->|runs on changes| Config
    CI1 -.->|runs on changes| New
    CI2 -.->|analyzes| Config
    CI3 -.->|legacy CI| Config

    Mod -->|"declares module"| Config
    Mod -->|"declares module"| New
    Meta1 -->|"docs"| Config
    Meta2 -->|"license"| Config

    %% Click Events
    click Config "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click Hasher "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click Member "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click New "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click Replica "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click LoadCalc "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click Distributor "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click Locator1 "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click LocatorN "https://github.com/buraksezer/consistent/blob/master/consistent.go"
    click Test "https://github.com/buraksezer/consistent/blob/master/consistent_test.go"
    click EX1 "https://github.com/buraksezer/consistent/blob/master/_examples/add_and_list.go"
    click EX2 "https://github.com/buraksezer/consistent/blob/master/_examples/load_distribution.go"
    click EX3 "https://github.com/buraksezer/consistent/blob/master/_examples/relocation_percentage.go"
    click EX4 "https://github.com/buraksezer/consistent/blob/master/_examples/sample.go"
    click CI1 "https://github.com/buraksezer/consistent/blob/master/.github/workflows/tests.yml"
    click CI2 "https://github.com/buraksezer/consistent/blob/master/.github/workflows/codeql-analysis.yml"
    click CI3 "https://github.com/buraksezer/consistent/blob/master/.travis.yml"
    click Mod "https://github.com/buraksezer/consistent/blob/master/go.mod"
    click Meta1 "https://github.com/buraksezer/consistent/blob/master/README.md"
    click Meta2 "https://github.com/buraksezer/consistent/tree/master/LICENSE"

    %% Styles
    classDef api fill:#cce5ff,stroke:#004085,color:#004085
    classDef internal fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef test fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef ci fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef metadata fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
