# stvp/dht architecture

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

- Interactive diagram: https://gitdiagram.com/stvp/dht
- Repository: https://github.com/stvp/dht

## Overview

##### Main Components
- DHT Node: The core component (implemented in node.go) that represents a cluster member. Each node maintains its own state, participates in key distribution, and runs an HTTP server for health checks.
- Consul Agent: An external service on 127.0.0.1:8500 used by each node for blocking API queries that refresh the local state. It acts as the backbone for membership verification.
- Rendezvous Hashing Mechanism: A logical component embedded within the DHT node’s functionality that determines which node should hold a specific key.
- Background Goroutine: A process inside each node that periodically issues blocking queries to Consul for refreshing state, logging any errors encountered.

##### Understand the Relationships & Interactions
- Each DHT node is responsible for joining and leaving the distributed hash table. When a node joins, it registers itself by starting an HTTP server from an ephemeral port, allowing Consul to check its liveness.
- Nodes communicate indirectly by updating their state based on Consul’s responses (using blocking queries) and by using the rendezvous hashing algorithm to decide key ownership.
- The HTTP server in each node serves the health check purpose, enabling Consul to verify node availability.

##### Architectural Patterns & Design Principles
- Distributed System with Service Discovery: Nodes work together through the Consul API, ensuring robust and dynamic membership.
- Rendezvous (Highest Random Weight) Hashing: This minimizes key reassignment disruption when nodes join or leave the system.
- Concurrency: Use of a background goroutine in each node ensures that the node’s local hash state is periodically refreshed without blocking the primary operations.
- Error logging: Consistent logging practices are implemented to trace errors in state refresh operations.

##### Relevant Technologies & Frameworks
- Go: The implementation language, with its capabilities for concurrency (goroutines) being a pivotal factor.
- Consul: For distributed configuration, service discovery, and maintaining the DHT membership.
- HTTP Server: Built into each node for health checks.
- Standard Go log package: For error logging.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "DHT Node"
        RH["Rendezvous Hashing Logic"]:::internal
        BG["Background Goroutine"]:::internal
        HS["Local HTTP Server (health checks)"]:::internal
        EL["Error Logging"]:::internal
    end

    CA["Consul Agent (127.0.0.1:8500)"]:::external

    BG -->|"blockingQueries"| CA
    CA -->|"healthCheckPing"| HS
    BG -->|"errorLogging"| EL
    RH -->|"keyAssignment"| HS

    click RH "https://github.com/stvp/dht/blob/master/node.go"
    click BG "https://github.com/stvp/dht/blob/master/node.go"
    click HS "https://github.com/stvp/dht/blob/master/node.go"
    click EL "https://github.com/stvp/dht/blob/master/node.go"
    click CA "https://github.com/stvp/dht/blob/master/node.go"

    classDef internal fill:#AED6F1,stroke:#1B4F72,stroke-width:2px,color:#000;
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px,color:#000;
```
