# onggiahuy97/chord architecture

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

- Interactive diagram: https://gitdiagram.com/onggiahuy97/chord
- Repository: https://github.com/onggiahuy97/chord

## Overview

##### Main Components of the System
- DHT Node (Chord module): Represented by src/chord.py, this component encapsulates the core Chord DHT algorithm.
- Network Connector: Represented by src/connector.py, handling communication between nodes.
- HTTP API Server: Launched via main.py. This component exposes endpoints (e.g., join node, get hash, insert, get, leave, node info) for clients to interact with the DHT.
- Leader Election Module: Signified by tests such as test_bully_leader_election.py, indicating that a mechanism exists (or is simulated) to elect a coordinator among nodes.
- Broadcast/Gossip Mechanisms: Tested via test_network_broadcast.py and test_gossiping.py, indicating support for peer-to-peer information flow.
- Failure Detector: Validated by test_failure_detector.py, ensuring system reliability in face of node failures.
- Supporting Elements: Docker configuration (Dockerfile), process cleanup (cleanup_port.py), and build/deployment scripts (Makefile, setup.py) indicate overarching deployment and operational considerations.

##### Relationships and Interactions
- API Endpoint ↔ DHT Node: The HTTP server handles client requests by interacting with the Chord module to perform DHT operations (join, search, insert, etc.).
- DHT Nodes Interconnection: Each node communicates with others using the Network Connector to maintain the ring structure and share state. This includes interactions for routing, leader election notifications, broadcast messages, and gossip updates.
- Leader Election, Broadcast, Gossip, and Failure Detection are integrated within or interacting with the DHT component to enhance node coordination and resiliency.
- Deployment Environment: Docker usage should be represented to show that the entire system is meant to run in containerized environments, accessible on port 5000 by default.

##### Architectural Patterns and Design Principles
- Distributed Systems & Peer-to-Peer Networking: Emphasize the distributed nature of the chord ring and the routing mechanism among nodes.
- Modular Design: The separation into distinct modules for chord, connector, and even testing different distributed functionalities illustrate a modular design.
- API-Based Interaction: The usage of REST API endpoints denotes clear separation between the client interface and the underlying DHT logic.
- Resilient and Decentralized Coordination: The inclusion of leader election, gossip, and failure detector emphasizes fault tolerance and dynamic membership management.

##### Relevant Technologies and Frameworks
- Python 3.12 with dependencies listed in requirements.txt.
- Docker for containerizing the application.
- Core networking and HTTP mechanisms used in main.py and the connector, even if not explicitly mentioned, should be depicted as integral to communication.

##### Overall
- The goal is to create a “big picture” view that helps a principal software engineer immediately understand the system’s building blocks, their responsibilities, and how they collaborate to implement a reliable Chord DHT with added distributed functionalities like leader election, gossip protocols, and failure detection.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    subgraph "External Clients"
        CLIENT["Client Request"]:::client
        UI["Chord UI Client"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        API["HTTP API Server"]:::api
    end

    %% Distributed DHT Node
    subgraph "Distributed DHT Node"
        CHORD["Chord Module"]:::dht
        NET["Network Connector"]:::network
        LE["Leader Election"]:::control
        NB["Network Broadcast"]:::control
        GP["Gossip Protocol"]:::control
        FD["Failure Detector"]:::control
    end

    %% Deployment and Utilities
    subgraph "Deployment and Utilities"
        DOCKER["Docker Configuration"]:::deploy
        CLEAN["Process Cleanup Utility"]:::util
        subgraph "Build/Deployment Scripts"
            MAKE["Makefile"]:::deploy
            SETUP["setup.py"]:::deploy
        end
    end

    %% Connections between components
    CLIENT -->|"APIRequest"| API
    UI -->|"SimulatedRequest"| API
    API -->|"HandlesRequest"| CHORD
    CHORD -->|"Communicates"| NET
    CHORD -->|"Triggers"| LE
    CHORD -->|"Broadcasts"| NB
    CHORD -->|"Gossips"| GP
    CHORD -->|"Checks"| FD

    %% Deployment links
    DOCKER -->|"Hosts"| API
    MAKE -->|"Builds"| API
    MAKE -->|"Builds"| CHORD
    SETUP -->|"Deploys"| API
    CLEAN -->|"CleansPorts"| DOCKER

    %% Click Events
    click API "https://github.com/onggiahuy97/chord/blob/main/main.py"
    click CHORD "https://github.com/onggiahuy97/chord/blob/main/src/chord.py"
    click NET "https://github.com/onggiahuy97/chord/blob/main/src/connector.py"
    click LE "https://github.com/onggiahuy97/chord/blob/main/test/test_bully_leader_election.py"
    click NB "https://github.com/onggiahuy97/chord/blob/main/test/test_network_broadcast.py"
    click GP "https://github.com/onggiahuy97/chord/blob/main/test/test_gossiping.py"
    click FD "https://github.com/onggiahuy97/chord/blob/main/test/test_failure_detector.py"
    click DOCKER "https://github.com/onggiahuy97/chord/tree/main/Dockerfile"
    click CLEAN "https://github.com/onggiahuy97/chord/blob/main/cleanup_port.py"
    click MAKE "https://github.com/onggiahuy97/chord/tree/main/Makefile"
    click SETUP "https://github.com/onggiahuy97/chord/blob/main/setup.py"

    %% Class Definitions for colors
    classDef api fill:#a1c4fd,stroke:#000,stroke-width:2px;
    classDef dht fill:#ffdd99,stroke:#000,stroke-width:2px;
    classDef network fill:#d1ffd1,stroke:#000,stroke-width:2px;
    classDef control fill:#ffb3b3,stroke:#000,stroke-width:2px;
    classDef deploy fill:#c2dfff,stroke:#000,stroke-width:2px;
    classDef util fill:#e6ccff,stroke:#000,stroke-width:2px;
    classDef client fill:#f2d7ee,stroke:#000,stroke-width:2px;
```
