# hajdukdusan/proplyd architecture

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

- Interactive diagram: https://gitdiagram.com/hajdukdusan/proplyd
- Repository: https://github.com/hajdukdusan/proplyd

## Overview

proplyd is a centralized, namespace-configurable cache in front of etcd. Applications use the Go client, which normally sends cache operations over gRPC and falls back to its configured backing store when the cache is unavailable; cache-aside reads also load from that store and offer the result back to the cache. On the server, the gRPC service delegates to the cache engine, which applies per-namespace read/write strategies and revision-aware consistency, stores entries in an eviction-managed in-memory store, and synchronizes changes from etcd watches. The README documents additional strategies and eviction options not traceable through the sampled excerpts; their paths are shown only where supported by the tree.

Main entry points: [`cache/namespace.go`](https://github.com/hajdukdusan/proplyd/blob/main/cache/namespace.go) (Namespace runtime), [`client/client.go`](https://github.com/hajdukdusan/proplyd/blob/main/client/client.go) (Go client), [`backend/backend.go`](https://github.com/hajdukdusan/proplyd/blob/main/backend/backend.go) (Backend interface), [`cmd/proplyd/main.go`](https://github.com/hajdukdusan/proplyd/blob/main/cmd/proplyd/main.go) (Server entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client access"]
  node_client_sdk["Go client<br/>[client.go]"]
  node_protocol["Shared config<br/>[config.go]"]
end

subgraph group_service["Cache service"]
  node_grpc_api["gRPC API<br/>[cache.proto]"]
  node_server["gRPC service<br/>[server.go]"]
  node_engine["Cache engine<br/>[engine.go]"]
  node_daemon["Server entry point<br/>[main.go]"]
end

subgraph group_consistency["Consistency and policies"]
  node_namespace["Namespace runtime<br/>[namespace.go]"]
  node_changelog["Revision changelog<br/>[changelog.go]"]
  node_watch["Watch sync<br/>[watch.go]"]
  node_writebehind["Write-behind flusher<br/>[writebehind.go]"]
  node_hot_store["Eviction store<br/>[hot.go]"]
end

subgraph group_storage["Backing storage"]
  node_backend_api["Backend interface<br/>[backend.go]"]
  node_etcd_adapter["etcd adapter<br/>[etcd.go]"]
  node_memory_backend[("Memory backend<br/>[memory.go]")]
end

node_apps(("Applications"))
node_etcd[("etcd cluster")]

node_apps -->|"uses"| node_client_sdk
node_client_sdk -->|"sends RPCs"| node_grpc_api
node_client_sdk -->|"uses config"| node_protocol
node_client_sdk -.->|"fallback reads/writes"| node_etcd_adapter
node_server -->|"implements"| node_grpc_api
node_server -->|"delegates operations"| node_engine
node_engine -->|"routes operations"| node_namespace
node_namespace -->|"reads/writes entries"| node_hot_store
node_namespace -->|"loads and mutates"| node_backend_api
node_namespace -->|"checks revisions"| node_changelog
node_watch -->|"starts watch"| node_backend_api
node_watch -->|"applies events"| node_namespace
node_writebehind -->|"flushes batches"| node_backend_api
node_etcd_adapter -->|"reads/writes/watches"| node_etcd
node_memory_backend -.->|"implements"| node_backend_api
node_daemon -->|"creates"| node_engine
node_daemon -->|"configures backend"| node_etcd_adapter
node_daemon -->|"starts service"| node_server

click node_client_sdk "https://github.com/hajdukdusan/proplyd/blob/main/client/client.go"
click node_protocol "https://github.com/hajdukdusan/proplyd/blob/main/protocol/config.go"
click node_grpc_api "https://github.com/hajdukdusan/proplyd/blob/main/api/proplyd/v1/cache.proto"
click node_server "https://github.com/hajdukdusan/proplyd/blob/main/server/server.go"
click node_engine "https://github.com/hajdukdusan/proplyd/blob/main/cache/engine.go"
click node_namespace "https://github.com/hajdukdusan/proplyd/blob/main/cache/namespace.go"
click node_changelog "https://github.com/hajdukdusan/proplyd/blob/main/cache/changelog.go"
click node_watch "https://github.com/hajdukdusan/proplyd/blob/main/cache/watch.go"
click node_writebehind "https://github.com/hajdukdusan/proplyd/blob/main/cache/writebehind.go"
click node_hot_store "https://github.com/hajdukdusan/proplyd/blob/main/store/hot.go"
click node_backend_api "https://github.com/hajdukdusan/proplyd/blob/main/backend/backend.go"
click node_etcd_adapter "https://github.com/hajdukdusan/proplyd/blob/main/backend/etcd/etcd.go"
click node_memory_backend "https://github.com/hajdukdusan/proplyd/blob/main/backend/memory/memory.go"
click node_daemon "https://github.com/hajdukdusan/proplyd/blob/main/cmd/proplyd/main.go"

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_sdk,node_protocol toneBlue
class node_grpc_api,node_server,node_engine,node_daemon,node_etcd toneAmber
class node_namespace,node_changelog,node_watch,node_writebehind,node_hot_store toneMint
class node_backend_api,node_etcd_adapter,node_memory_backend toneRose
class node_apps toneIndigo
```

## Components

### Client access

- [Go client](https://github.com/hajdukdusan/proplyd/blob/main/client/client.go): `client/client.go`
- [Shared config](https://github.com/hajdukdusan/proplyd/blob/main/protocol/config.go): `protocol/config.go`

### Cache service

- [gRPC API](https://github.com/hajdukdusan/proplyd/blob/main/api/proplyd/v1/cache.proto): `api/proplyd/v1/cache.proto`
- [gRPC service](https://github.com/hajdukdusan/proplyd/blob/main/server/server.go): `server/server.go`
- [Cache engine](https://github.com/hajdukdusan/proplyd/blob/main/cache/engine.go): `cache/engine.go`
- [Server entry point](https://github.com/hajdukdusan/proplyd/blob/main/cmd/proplyd/main.go): `cmd/proplyd/main.go`

### Consistency and policies

- [Namespace runtime](https://github.com/hajdukdusan/proplyd/blob/main/cache/namespace.go): `cache/namespace.go`
- [Revision changelog](https://github.com/hajdukdusan/proplyd/blob/main/cache/changelog.go): `cache/changelog.go`
- [Watch sync](https://github.com/hajdukdusan/proplyd/blob/main/cache/watch.go): `cache/watch.go`
- [Write-behind flusher](https://github.com/hajdukdusan/proplyd/blob/main/cache/writebehind.go): `cache/writebehind.go`
- [Eviction store](https://github.com/hajdukdusan/proplyd/blob/main/store/hot.go): `store/hot.go`

### Backing storage

- [Backend interface](https://github.com/hajdukdusan/proplyd/blob/main/backend/backend.go): `backend/backend.go`
- [etcd adapter](https://github.com/hajdukdusan/proplyd/blob/main/backend/etcd/etcd.go): `backend/etcd/etcd.go`
- [Memory backend](https://github.com/hajdukdusan/proplyd/blob/main/backend/memory/memory.go): `backend/memory/memory.go`

### Other components

- **Applications**
- **etcd cluster**

## Connections

- Applications → Go client: uses
- Go client → gRPC API: sends RPCs
- Go client → Shared config: uses config
- Go client → etcd adapter: fallback reads/writes
- gRPC service → gRPC API: implements
- gRPC service → Cache engine: delegates operations
- Cache engine → Namespace runtime: routes operations
- Namespace runtime → Eviction store: reads/writes entries
- Namespace runtime → Backend interface: loads and mutates
- Namespace runtime → Revision changelog: checks revisions
- Watch sync → Backend interface: starts watch
- Watch sync → Namespace runtime: applies events
- Write-behind flusher → Backend interface: flushes batches
- etcd adapter → etcd cluster: reads/writes/watches
- Memory backend → Backend interface: implements
- Server entry point → Cache engine: creates
- Server entry point → etcd adapter: configures backend
- Server entry point → gRPC service: starts service