# danielvegamyhre/minicache architecture

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

- Interactive diagram: https://gitdiagram.com/danielvegamyhre/minicache
- Repository: https://github.com/danielvegamyhre/minicache

## Overview

#### Purpose and Entry Points
Minicache is a Go distributed in-memory cache: each node owns an LRU store, while clients route keys with consistent hashing. Nodes dynamically form a cluster, elect a leader, and expose both HTTP and gRPC APIs.

The executable entry point is `main.go`, which parses node/runtime flags, creates a cache server, starts gRPC and HTTP listeners, registers with the cluster, initiates election/heartbeat monitoring, and handles shutdown. Programmatic server bootstrap is in `server/server.go`; consumer client entry points are in `client/client.go`.

#### Local Storage Layer
Each cache node contains a thread-safe, bounded O(1) LRU cache for key/value storage and eviction:
- `lru/lru.go`
- `server/server.go`

This is node-local storage; the system does not describe replication or durable persistence. Therefore a membership/ring change can remap future requests but does not imply data migration.

#### Client Routing and Membership Watcher
The client owns the consistent-hash ring and selects a target node for every Get/Put. It initializes from configured genesis nodes, obtains current cluster state from the leader, and watches for membership changes to add/remove ring members:
- `client/client.go`
- `ring/ring.go`
- `configs/nodes-local-with-mTLS.json`

This is the principal request-routing boundary: client-to-node traffic reaches only the node selected for a key, using either HTTP or gRPC.

#### Node Service Interfaces
A cache server hosts both public request protocols and the inter-node control RPCs used for registration, state propagation, heartbeat, and election:
- `server/server.go`
- `pb/cache_service.proto`
- `pb/cache_service_grpc.pb.go`

Protocol contracts are defined in protobuf and generated Go bindings under `pb/`. HTTP is a parallel interface on the server rather than a separate application tier.

#### Cluster Membership and Discovery
Nodes begin from a JSON genesis-node configuration. A dynamically started node contacts configured initial nodes to register; receiving nodes update their in-memory membership and propagate the updated list through the cluster:
- `server/cluster.go`
- `node/node.go`
- `configs/nodes-docker-with-mTLS.json`

Genesis configuration is a bootstrap dependency, not a fixed cluster-size limit: once a reachable genesis node accepts registration, arbitrary additional nodes can join.

#### Leader Election and Failure Handling
The cluster uses the Bully algorithm to elect a leader. The leader tracks node reachability through heartbeats and provides active membership to clients; followers monitor leader heartbeat and trigger a new election on failure:
- `server/election.go`
- `server/cluster.go`
- `server/server.go`

Control-plane availability depends on successful election and leader monitoring. Client rings are eventually refreshed from the leader’s cluster view.

#### Runtime, Deployment, and Security
The primary runtime is Go with concurrent goroutines for serving, monitoring, and shutdown coordination. Nodes can run locally or as Docker Compose services:
- `Dockerfile.server`
- `docker-compose.yml`
- `Dockerfile.client`

TLS can be disabled, enabled, or configured for mutual TLS between clients/nodes and servers. Certificates and SAN generation inputs are repository-managed:
- `certs/gen.sh`
- `certs/client-ext.cnf`
- `certs/server-ext.cnf`

Main entry points: [`server/cluster.go`](https://github.com/danielvegamyhre/minicache/blob/main/server/cluster.go) (Membership manager), [`server/server.go`](https://github.com/danielvegamyhre/minicache/blob/main/server/server.go) (Cache server), [`client/client.go`](https://github.com/danielvegamyhre/minicache/blob/main/client/client.go) (Cache client), [`docker-compose.yml`](https://github.com/danielvegamyhre/minicache/blob/main/docker-compose.yml) (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Routing"]
  node_client_api["Cache client<br/>Go client<br/>[client.go]"]
  node_ring{{"Consistent hash ring<br/>key router<br/>[ring.go]"}}
  node_genesis_local["Local genesis nodes<br/>JSON bootstrap config"]
end

subgraph group_node["Cache Node"]
  node_server["Cache server<br/>Go service<br/>[server.go]"]
  node_lru[("Local LRU store<br/>in-memory cache<br/>[lru.go]")]
  node_contracts["Protocol contracts<br/>protobuf"]
  node_grpc_bindings["gRPC bindings<br/>generated Go"]
end

subgraph group_control["Cluster Control Plane"]
  node_cluster["Membership manager<br/>cluster state<br/>[cluster.go]"]
  node_node_identity["Node model<br/>member identity<br/>[node.go]"]
  node_election{{"Bully election<br/>leader election<br/>[election.go]"}}
end

subgraph group_runtime["Runtime &amp; Deployment"]
  node_entrypoint["Node executable<br/>Go entry point<br/>[main.go]"]
  node_genesis_docker["Docker genesis nodes<br/>JSON bootstrap config"]
  node_compose["Docker Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_server_image["Server image<br/>container build<br/>[Dockerfile.server]"]
  node_client_image["Client image<br/>container build<br/>[Dockerfile.client]"]
  node_tls_assets["TLS certificate setup<br/>security assets<br/>[gen.sh]"]
end

node_entrypoint -->|"bootstraps"| node_server
node_server -->|"reads and writes"| node_lru
node_contracts -->|"generates"| node_grpc_bindings
node_grpc_bindings -->|"implements gRPC API"| node_server
node_client_api -->|"selects node by key"| node_ring
node_client_api -->|"Get/Put via HTTP or gRPC"| node_server
node_genesis_local -->|"initializes discovery"| node_client_api
node_genesis_docker -->|"supplies initial contacts"| node_cluster
node_server -->|"registers and serves control RPCs"| node_cluster
node_cluster -->|"tracks members"| node_node_identity
node_cluster -->|"membership for election"| node_election
node_election -->|"leader heartbeats and failure detection"| node_cluster
node_cluster -->|"leader provides state updates"| node_client_api
node_cluster -->|"add/remove members"| node_ring
node_compose -->|"builds server nodes"| node_server_image
node_compose -->|"builds client runtime"| node_client_image
node_tls_assets -.->|"secures client and node traffic"| node_server
node_tls_assets -.->|"enables TLS or mTLS"| node_client_api

click node_entrypoint "https://github.com/danielvegamyhre/minicache/blob/main/main.go"
click node_server "https://github.com/danielvegamyhre/minicache/blob/main/server/server.go"
click node_lru "https://github.com/danielvegamyhre/minicache/blob/main/lru/lru.go"
click node_contracts "https://github.com/danielvegamyhre/minicache/blob/main/pb/cache_service.proto"
click node_grpc_bindings "https://github.com/danielvegamyhre/minicache/blob/main/pb/cache_service_grpc.pb.go"
click node_client_api "https://github.com/danielvegamyhre/minicache/blob/main/client/client.go"
click node_ring "https://github.com/danielvegamyhre/minicache/blob/main/ring/ring.go"
click node_genesis_local "https://github.com/danielvegamyhre/minicache/blob/main/configs/nodes-local-with-mTLS.json"
click node_cluster "https://github.com/danielvegamyhre/minicache/blob/main/server/cluster.go"
click node_node_identity "https://github.com/danielvegamyhre/minicache/blob/main/node/node.go"
click node_election "https://github.com/danielvegamyhre/minicache/blob/main/server/election.go"
click node_genesis_docker "https://github.com/danielvegamyhre/minicache/blob/main/configs/nodes-docker-with-mTLS.json"
click node_compose "https://github.com/danielvegamyhre/minicache/blob/main/docker-compose.yml"
click node_server_image "https://github.com/danielvegamyhre/minicache/blob/main/Dockerfile.server"
click node_client_image "https://github.com/danielvegamyhre/minicache/blob/main/Dockerfile.client"
click node_tls_assets "https://github.com/danielvegamyhre/minicache/blob/main/certs/gen.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_api,node_ring,node_genesis_local toneBlue
class node_server,node_lru,node_contracts,node_grpc_bindings toneAmber
class node_cluster,node_node_identity,node_election toneMint
class node_entrypoint,node_genesis_docker,node_compose,node_server_image,node_client_image,node_tls_assets toneRose
```

## Components

### Client Routing

- [Cache client](https://github.com/danielvegamyhre/minicache/blob/main/client/client.go): Go client · Routes each Get/Put to its selected node. · `client/client.go`
- [Consistent hash ring](https://github.com/danielvegamyhre/minicache/blob/main/ring/ring.go): key router · Maps keys to active cache nodes. · `ring/ring.go`
- [Local genesis nodes](https://github.com/danielvegamyhre/minicache/blob/main/configs/nodes-local-with-mTLS.json): JSON bootstrap config · `configs/nodes-local-with-mTLS.json`

### Cache Node

- [Cache server](https://github.com/danielvegamyhre/minicache/blob/main/server/server.go): Go service · Hosts cache APIs and node lifecycle. · `server/server.go`
- [Local LRU store](https://github.com/danielvegamyhre/minicache/blob/main/lru/lru.go): in-memory cache · Thread-safe bounded O(1) key/value storage. · `lru/lru.go`
- [Protocol contracts](https://github.com/danielvegamyhre/minicache/blob/main/pb/cache_service.proto): protobuf · Defines cache and cluster RPCs. · `pb/cache_service.proto`
- [gRPC bindings](https://github.com/danielvegamyhre/minicache/blob/main/pb/cache_service_grpc.pb.go): generated Go · `pb/cache_service_grpc.pb.go`

### Cluster Control Plane

- [Membership manager](https://github.com/danielvegamyhre/minicache/blob/main/server/cluster.go): cluster state · Registers nodes and propagates active membership. · `server/cluster.go`
- [Node model](https://github.com/danielvegamyhre/minicache/blob/main/node/node.go): member identity · `node/node.go`
- [Bully election](https://github.com/danielvegamyhre/minicache/blob/main/server/election.go): leader election · Elects a leader and monitors leader failure. · `server/election.go`

### Runtime & Deployment

- [Node executable](https://github.com/danielvegamyhre/minicache/blob/main/main.go): Go entry point · Parses flags and starts node services. · `main.go`
- [Docker genesis nodes](https://github.com/danielvegamyhre/minicache/blob/main/configs/nodes-docker-with-mTLS.json): JSON bootstrap config · `configs/nodes-docker-with-mTLS.json`
- [Docker Compose](https://github.com/danielvegamyhre/minicache/blob/main/docker-compose.yml): deployment · Runs multi-node local deployment. · `docker-compose.yml`
- [Server image](https://github.com/danielvegamyhre/minicache/blob/main/Dockerfile.server): container build · `Dockerfile.server`
- [Client image](https://github.com/danielvegamyhre/minicache/blob/main/Dockerfile.client): container build · `Dockerfile.client`
- [TLS certificate setup](https://github.com/danielvegamyhre/minicache/blob/main/certs/gen.sh): security assets · Generates certificates and SAN inputs for TLS or mTLS. · `certs/gen.sh`

## Connections

- Node executable → Cache server: bootstraps
- Cache server → Local LRU store: reads and writes
- Protocol contracts → gRPC bindings: generates
- gRPC bindings → Cache server: implements gRPC API
- Cache client → Consistent hash ring: selects node by key
- Cache client → Cache server: Get/Put via HTTP or gRPC · Requests go only to the selected node.
- Local genesis nodes → Cache client: initializes discovery
- Docker genesis nodes → Membership manager: supplies initial contacts
- Cache server → Membership manager: registers and serves control RPCs
- Membership manager → Node model: tracks members
- Membership manager → Bully election: membership for election
- Bully election → Membership manager: leader heartbeats and failure detection
- Membership manager → Cache client: leader provides state updates · Client eventually refreshes ring membership.
- Membership manager → Consistent hash ring: add/remove members
- Docker Compose → Server image: builds server nodes
- Docker Compose → Client image: builds client runtime
- TLS certificate setup → Cache server: secures client and node traffic
- TLS certificate setup → Cache client: enables TLS or mTLS