# codenamed22/omnidict architecture

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

- Interactive diagram: https://gitdiagram.com/codenamed22/omnidict
- Repository: https://github.com/codenamed22/omnidict

## Overview

##### Project Type & Purpose
- Type: Distributed, fault-tolerant service written in Go.
- Purpose: Expose a gRPC API for Put/Get/Join, distribute keys via consistent hashing, replicate each shard with Raft for strong consistency and leader election, and survive node failures.

##### File Structure
- Top-level files:
– ring.go + internal/ring/ring.go: Consistent-hash ring implementation.
– internal/store/store.go: Per-shard store logic + Raft integration.
– proto/kv.proto + generated Go files: gRPC service definition (Put/Get/Join).
– docker-compose.yml & DockerFile: Containerization & multi-node orchestration.
– design.md: High-level design notes.
- Patterns:
– Separation of concerns: API layer (ring.go), ring logic, Raft/store logic.
– Modular Go packages under /internal.

##### Extract Additional Insights from README
- Consistent hashing to map keys → N nodes (≤25% movement on rebalance).
- Raft group per shard (leader-based writes, log-replication).
- gRPC API surface.
- CLI test script spawns multiple nodes, kills one, verifies correctness.

##### Main Components & Their Relationships
a. Clients
– CLI or application code issuing gRPC calls (Put, Get, Join).
b. API Gateway / gRPC Server
– ring.go + proto handlers: receives RPCs, consults the ring.
c. Consistent-Hash Ring
– internal/ring package: determines which shard/node owns a key.
d. Node Instances (3–5 replicas)
– Each node runs:
1. A gRPC server.
2. Ring service (listens for Join, membership changes).
3. Shard(s) host:
- Raft module (etcd/HashiCorp Raft) for consensus.
- In-memory key-value store behind Raft.
e. Raft Peer Communication
– Leader election & log replication over TCP between nodes in the same shard group.
f. Cluster Membership
– Join RPC → updates ring membership → triggers rebalance.

##### Architectural Patterns & Design Principles
- Consistent Hashing: decouples key-to-shard mapping, minimal remapping.
- RAFT Consensus: strong consistency, leader-based writes, quorum reads/writes.
- Separation of Concerns:
– API layer (RPC)
– Ring layer (sharding + membership)
– Store layer (consensus + data)
- Containerization: Docker + docker-compose for multi-node testing.

##### Final Checklist
– Each component clearly labeled.
– Deployment artifacts (Docker, compose) shown externally.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client\n(CLI/Application)"]:::external

    subgraph "Cluster of OmniDict Nodes"
        direction TB
        subgraph "Node 1"
            direction TB
            API1["gRPC Server"]:::api
            Ring1["Ring Module"]:::ring
            Raft1["Raft + KV Store"]:::raft
        end
        subgraph "Node 2"
            direction TB
            API2["gRPC Server"]:::api
            Ring2["Ring Module"]:::ring
            Raft2["Raft + KV Store"]:::raft
        end
        subgraph "Node 3"
            direction TB
            API3["gRPC Server"]:::api
            Ring3["Ring Module"]:::ring
            Raft3["Raft + KV Store"]:::raft
        end
    end

    subgraph "Project Artifacts"
        direction TB
        ProtoDef["kv.proto"]:::external
        ProtoPB["kv.pb.go"]:::external
        ProtoGRPC["kv_grpc.pb.go"]:::external
        DockerFile["DockerFile"]:::external
        Compose["docker-compose.yml"]:::external
        Design["design.md"]:::external
        GoMod["go.mod"]:::external
        Readme["README.md"]:::external
    end

    Client -->|"PutRequest / GetRequest / JoinRequest"| API1
    Client -->|"PutRequest / GetRequest / JoinRequest"| API2
    Client -->|"PutRequest / GetRequest / JoinRequest"| API3

    API1 -->|"lookup shard"| Ring1
    Ring1 -->|"route to leader"| Raft1

    API2 -->|"lookup shard"| Ring2
    Ring2 -->|"route to leader"| Raft2

    API3 -->|"lookup shard"| Ring3
    Ring3 -->|"route to leader"| Raft3

    Raft1 <-->|"Raft AppendEntries & Heartbeats"| Raft2
    Raft2 <-->|"Raft AppendEntries & Heartbeats"| Raft3
    Raft3 <-->|"Raft AppendEntries & Heartbeats"| Raft1

    click API1 "https://github.com/codenamed22/omnidict/blob/main/ring.go"
    click API2 "https://github.com/codenamed22/omnidict/blob/main/ring.go"
    click API3 "https://github.com/codenamed22/omnidict/blob/main/ring.go"
    click Ring1 "https://github.com/codenamed22/omnidict/blob/main/internal/ring/ring.go"
    click Ring2 "https://github.com/codenamed22/omnidict/blob/main/internal/ring/ring.go"
    click Ring3 "https://github.com/codenamed22/omnidict/blob/main/internal/ring/ring.go"
    click Raft1 "https://github.com/codenamed22/omnidict/blob/main/internal/store/store.go"
    click Raft2 "https://github.com/codenamed22/omnidict/blob/main/internal/store/store.go"
    click Raft3 "https://github.com/codenamed22/omnidict/blob/main/internal/store/store.go"
    click ProtoDef "https://github.com/codenamed22/omnidict/blob/main/proto/kv.proto"
    click ProtoPB "https://github.com/codenamed22/omnidict/blob/main/proto/kv.pb.go"
    click ProtoGRPC "https://github.com/codenamed22/omnidict/blob/main/proto/kv_grpc.pb.go"
    click DockerFile "https://github.com/codenamed22/omnidict/tree/main/DockerFile"
    click Compose "https://github.com/codenamed22/omnidict/blob/main/docker-compose.yml"
    click Design "https://github.com/codenamed22/omnidict/blob/main/design.md"
    click GoMod "https://github.com/codenamed22/omnidict/blob/main/go.mod"
    click Readme "https://github.com/codenamed22/omnidict/blob/main/README.md"

    classDef api fill:#D0E6FF,stroke:#003366,stroke-width:2px
    classDef ring fill:#E6FFE6,stroke:#006600,stroke-width:2px
    classDef raft fill:#FFE6CC,stroke:#CC6600,stroke-width:2px
    classDef external fill:#F2F2F2,stroke:#999999,stroke-width:1px
```
