# etcd-io/etcd architecture

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

- Interactive diagram: https://gitdiagram.com/etcd-io/etcd
- Repository: https://github.com/etcd-io/etcd
- Video tour (about a minute): https://gitdiagram.com/etcd-io/etcd/video

## Overview

etcd is a distributed, Raft-backed key-value store. The principal workflow is a user issuing a command or application request through the client API; a member serves it over gRPC and replicates state across the cluster. The graph also preserves documented client capabilities and the watch-backed cache. The README and excerpts establish the public workflow and selected implementation details; several internal server-stage links are therefore shown as unverified rather than asserted as source-verified calls.

Main entry points: [`server/etcdserver/api/v3rpc`](https://github.com/etcd-io/etcd/tree/main/server/etcdserver/api/v3rpc) (gRPC handlers), [`server/etcdserver/server.go`](https://github.com/etcd-io/etcd/blob/main/server/etcdserver/server.go) (Etcd server), [`client/v3/client.go`](https://github.com/etcd-io/etcd/blob/main/client/v3/client.go) (Go client), [`server/storage/storage.go`](https://github.com/etcd-io/etcd/blob/main/server/storage/storage.go) (Raft storage adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry points"]
  node_ctl["etcdctl commands<br/>[put_command.go]"]
  node_client["Go client<br/>[client.go]"]
  node_api["gRPC API definitions<br/>[rpc.proto]"]
end

subgraph group_serving["Member serving"]
  node_embed["Embedded server<br/>[etcd.go]"]
  node_server["Etcd server<br/>[server.go]"]
  node_rpc["gRPC handlers"]
end

subgraph group_consensus["Consensus and storage"]
  node_raft["Raft consensus<br/>[raft.go]"]
  node_peer["Peer transport"]
  node_storage["Raft storage adapter<br/>[storage.go]"]
  node_wal[("Write-ahead log<br/>[wal.go]")]
  node_backend[("Persistent backend<br/>[backend.go]")]
end

subgraph group_features["Data services"]
  node_mvcc[("MVCC key store<br/>[kvstore.go]")]
  node_txn["Transactions<br/>[txn.go]"]
  node_auth["Authentication<br/>[store.go]"]
  node_lease["Leases<br/>[lessor.go]"]
  node_watch["Watch service<br/>[watch.go]"]
  node_membership["Cluster membership<br/>[cluster.go]"]
  node_snapshot["Snapshot operations<br/>[snapshotter.go]"]
end

subgraph group_clientfeatures["Client capabilities"]
  node_cache["Watch-backed cache<br/>[cache.go]"]
  node_concurrency["Concurrency recipes<br/>[session.go]"]
end

node_user(("User or application"))
node_external(("Peer members"))

node_user -->|"issues commands"| node_ctl
node_user -->|"uses API"| node_client
node_ctl -->|"requests keys"| node_server
node_client -->|"uses gRPC"| node_api
node_api -.->|"defines services"| node_rpc
node_embed -->|"starts server"| node_server
node_server -.->|"serves requests"| node_rpc
node_server -.->|"coordinates consensus"| node_raft
node_raft -.->|"exchanges Raft traffic"| node_peer
node_raft -.->|"persists Raft state"| node_storage
node_storage -->|"writes entries"| node_wal
node_storage -->|"releases snapshots"| node_snapshot
node_storage -.->|"stores state"| node_backend
node_rpc -.->|"dispatches transactions"| node_txn
node_txn -.->|"updates key state"| node_mvcc
node_rpc -.->|"checks access"| node_auth
node_rpc -.->|"serves lease calls"| node_lease
node_rpc -.->|"serves watches"| node_watch
node_rpc -.->|"serves membership"| node_membership
node_client -->|"supplies watch and KV"| node_cache
node_cache -.->|"reads revisions"| node_mvcc
node_client -.->|"supports recipes"| node_concurrency
node_server -.->|"replicates with peers"| node_external

click node_ctl "https://github.com/etcd-io/etcd/blob/main/etcdctl/ctlv3/command/put_command.go"
click node_client "https://github.com/etcd-io/etcd/blob/main/client/v3/client.go"
click node_api "https://github.com/etcd-io/etcd/blob/main/api/etcdserverpb/rpc.proto"
click node_embed "https://github.com/etcd-io/etcd/blob/main/server/embed/etcd.go"
click node_server "https://github.com/etcd-io/etcd/blob/main/server/etcdserver/server.go"
click node_rpc "https://github.com/etcd-io/etcd/tree/main/server/etcdserver/api/v3rpc"
click node_raft "https://github.com/etcd-io/etcd/blob/main/server/etcdserver/raft.go"
click node_peer "https://github.com/etcd-io/etcd/tree/main/server/etcdserver/api/rafthttp"
click node_storage "https://github.com/etcd-io/etcd/blob/main/server/storage/storage.go"
click node_wal "https://github.com/etcd-io/etcd/blob/main/server/storage/wal/wal.go"
click node_backend "https://github.com/etcd-io/etcd/blob/main/server/storage/backend/backend.go"
click node_mvcc "https://github.com/etcd-io/etcd/blob/main/server/storage/mvcc/kvstore.go"
click node_txn "https://github.com/etcd-io/etcd/blob/main/server/etcdserver/txn/txn.go"
click node_auth "https://github.com/etcd-io/etcd/blob/main/server/auth/store.go"
click node_lease "https://github.com/etcd-io/etcd/blob/main/server/lease/lessor.go"
click node_watch "https://github.com/etcd-io/etcd/blob/main/server/etcdserver/api/v3rpc/watch.go"
click node_membership "https://github.com/etcd-io/etcd/blob/main/server/etcdserver/api/membership/cluster.go"
click node_cache "https://github.com/etcd-io/etcd/blob/main/cache/cache.go"
click node_concurrency "https://github.com/etcd-io/etcd/blob/main/client/v3/concurrency/session.go"
click node_snapshot "https://github.com/etcd-io/etcd/blob/main/server/etcdserver/api/snap/snapshotter.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_ctl,node_client,node_api,node_user toneBlue
class node_embed,node_server,node_rpc toneAmber
class node_raft,node_peer,node_storage,node_wal,node_backend toneMint
class node_mvcc,node_txn,node_auth,node_lease,node_watch,node_membership,node_snapshot toneRose
class node_cache,node_concurrency,node_external toneIndigo
```

## Components

### Client entry points

- [etcdctl commands](https://github.com/etcd-io/etcd/blob/main/etcdctl/ctlv3/command/put_command.go): `etcdctl/ctlv3/command/put_command.go`
- [Go client](https://github.com/etcd-io/etcd/blob/main/client/v3/client.go): `client/v3/client.go`
- [gRPC API definitions](https://github.com/etcd-io/etcd/blob/main/api/etcdserverpb/rpc.proto): `api/etcdserverpb/rpc.proto`

### Member serving

- [Embedded server](https://github.com/etcd-io/etcd/blob/main/server/embed/etcd.go): `server/embed/etcd.go`
- [Etcd server](https://github.com/etcd-io/etcd/blob/main/server/etcdserver/server.go): `server/etcdserver/server.go`
- [gRPC handlers](https://github.com/etcd-io/etcd/tree/main/server/etcdserver/api/v3rpc): `server/etcdserver/api/v3rpc`

### Consensus and storage

- [Raft consensus](https://github.com/etcd-io/etcd/blob/main/server/etcdserver/raft.go): `server/etcdserver/raft.go`
- [Peer transport](https://github.com/etcd-io/etcd/tree/main/server/etcdserver/api/rafthttp): `server/etcdserver/api/rafthttp`
- [Raft storage adapter](https://github.com/etcd-io/etcd/blob/main/server/storage/storage.go): `server/storage/storage.go`
- [Write-ahead log](https://github.com/etcd-io/etcd/blob/main/server/storage/wal/wal.go): `server/storage/wal/wal.go`
- [Persistent backend](https://github.com/etcd-io/etcd/blob/main/server/storage/backend/backend.go): `server/storage/backend/backend.go`

### Data services

- [MVCC key store](https://github.com/etcd-io/etcd/blob/main/server/storage/mvcc/kvstore.go): `server/storage/mvcc/kvstore.go`
- [Transactions](https://github.com/etcd-io/etcd/blob/main/server/etcdserver/txn/txn.go): `server/etcdserver/txn/txn.go`
- [Authentication](https://github.com/etcd-io/etcd/blob/main/server/auth/store.go): `server/auth/store.go`
- [Leases](https://github.com/etcd-io/etcd/blob/main/server/lease/lessor.go): `server/lease/lessor.go`
- [Watch service](https://github.com/etcd-io/etcd/blob/main/server/etcdserver/api/v3rpc/watch.go): `server/etcdserver/api/v3rpc/watch.go`
- [Cluster membership](https://github.com/etcd-io/etcd/blob/main/server/etcdserver/api/membership/cluster.go): `server/etcdserver/api/membership/cluster.go`
- [Snapshot operations](https://github.com/etcd-io/etcd/blob/main/server/etcdserver/api/snap/snapshotter.go): `server/etcdserver/api/snap/snapshotter.go`

### Client capabilities

- [Watch-backed cache](https://github.com/etcd-io/etcd/blob/main/cache/cache.go): `cache/cache.go`
- [Concurrency recipes](https://github.com/etcd-io/etcd/blob/main/client/v3/concurrency/session.go): `client/v3/concurrency/session.go`

### Other components

- **User or application**
- **Peer members**

## Connections

- User or application → etcdctl commands: issues commands
- User or application → Go client: uses API
- etcdctl commands → Etcd server: requests keys
- Go client → gRPC API definitions: uses gRPC
- gRPC API definitions → gRPC handlers: defines services
- Embedded server → Etcd server: starts server (evidence: `server/embed/etcd.go`)
- Etcd server → gRPC handlers: serves requests
- Etcd server → Raft consensus: coordinates consensus
- Raft consensus → Peer transport: exchanges Raft traffic
- Raft consensus → Raft storage adapter: persists Raft state
- Raft storage adapter → Write-ahead log: writes entries (evidence: `server/storage/storage.go`)
- Raft storage adapter → Snapshot operations: releases snapshots (evidence: `server/storage/storage.go`)
- Raft storage adapter → Persistent backend: stores state
- gRPC handlers → Transactions: dispatches transactions
- Transactions → MVCC key store: updates key state
- gRPC handlers → Authentication: checks access
- gRPC handlers → Leases: serves lease calls
- gRPC handlers → Watch service: serves watches
- gRPC handlers → Cluster membership: serves membership
- Go client → Watch-backed cache: supplies watch and KV (evidence: `cache/cache.go`)
- Watch-backed cache → MVCC key store: reads revisions
- Go client → Concurrency recipes: supports recipes
- Etcd server → Peer members: replicates with peers
