# coreos/etcd architecture

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

- Interactive diagram: https://gitdiagram.com/coreos/etcd
- Repository: https://github.com/coreos/etcd

## Overview

etcd is a highly available distributed key-value store. The primary workflow is a user or application issuing requests through etcdctl or the Go client to a running member; members replicate state with Raft and serve reads and writes from the store. Major capabilities also include watches, leases, authentication, membership, maintenance and snapshots. The graph uses README statements and the supplied source excerpts; several internal subsystems are represented at directory level because their implementation was not sampled.

Main entry points: [`server/etcdserver/api/v3rpc`](https://github.com/coreos/etcd/tree/main/server/etcdserver/api/v3rpc) (gRPC API), [`server/etcdserver/server.go`](https://github.com/coreos/etcd/blob/main/server/etcdserver/server.go) (Etcd server), [`client/v3/client.go`](https://github.com/coreos/etcd/blob/main/client/v3/client.go) (Go client), [`server/etcdserver/raft.go`](https://github.com/coreos/etcd/blob/main/server/etcdserver/raft.go) (Raft consensus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and tools"]
  node_ctl["etcdctl"]
  node_client["Go client<br/>[client.go]"]
  node_cache["Watch cache<br/>[cache.go]"]
end

subgraph group_serving["Serving and APIs"]
  node_embedded["Embedded startup<br/>[etcd.go]"]
  node_grpc["gRPC API"]
  node_protocol["API definitions<br/>[rpc.proto]"]
  node_auth["Authentication"]
  node_lease["Leases"]
  node_watch["Watch API<br/>[watch.go]"]
  node_maintenance["Maintenance API<br/>[maintenance.go]"]
end

subgraph group_consensus["Cluster and consensus"]
  node_server["Etcd server<br/>[server.go]"]
  node_raft["Raft consensus<br/>[raft.go]"]
  node_membership["Cluster membership"]
  node_peer["Peer transport"]
end

subgraph group_persistence["Persistence and state"]
  node_kv[("MVCC key-value")]
  node_backend[("Storage backend")]
  node_wal[("Raft WAL")]
  node_snapshots[("Snapshots")]
end

node_user(("Operator or app"))
node_external(("Peer members"))

node_user -->|"runs commands"| node_ctl
node_user -->|"uses API"| node_client
node_ctl -.->|"issues requests"| node_client
node_client -->|"sends gRPC"| node_embedded
node_embedded -->|"starts"| node_server
node_server -.->|"serves requests"| node_grpc
node_grpc -->|"implements"| node_protocol
node_server -->|"replicates state"| node_raft
node_raft -.->|"exchanges messages"| node_peer
node_peer -->|"communicates"| node_external
node_server -.->|"manages members"| node_membership
node_server -.->|"applies requests"| node_kv
node_kv -.->|"persists state"| node_backend
node_raft -.->|"persists log"| node_wal
node_server -.->|"creates snapshots"| node_snapshots
node_grpc -.->|"authorizes requests"| node_auth
node_grpc -.->|"serves lease calls"| node_lease
node_grpc -.->|"serves watches"| node_watch
node_grpc -.->|"serves maintenance"| node_maintenance
node_client -->|"backs cache"| node_cache

click node_ctl "https://github.com/coreos/etcd/tree/main/etcdctl/ctlv3/command"
click node_client "https://github.com/coreos/etcd/blob/main/client/v3/client.go"
click node_cache "https://github.com/coreos/etcd/blob/main/cache/cache.go"
click node_embedded "https://github.com/coreos/etcd/blob/main/server/embed/etcd.go"
click node_grpc "https://github.com/coreos/etcd/tree/main/server/etcdserver/api/v3rpc"
click node_protocol "https://github.com/coreos/etcd/blob/main/api/etcdserverpb/rpc.proto"
click node_auth "https://github.com/coreos/etcd/tree/main/server/auth"
click node_server "https://github.com/coreos/etcd/blob/main/server/etcdserver/server.go"
click node_raft "https://github.com/coreos/etcd/blob/main/server/etcdserver/raft.go"
click node_membership "https://github.com/coreos/etcd/tree/main/server/etcdserver/api/membership"
click node_peer "https://github.com/coreos/etcd/tree/main/server/etcdserver/api/rafthttp"
click node_kv "https://github.com/coreos/etcd/tree/main/server/storage/mvcc"
click node_backend "https://github.com/coreos/etcd/tree/main/server/storage/backend"
click node_wal "https://github.com/coreos/etcd/tree/main/server/storage/wal"
click node_snapshots "https://github.com/coreos/etcd/tree/main/server/etcdserver/api/snap"
click node_lease "https://github.com/coreos/etcd/tree/main/server/lease"
click node_watch "https://github.com/coreos/etcd/blob/main/server/etcdserver/api/v3rpc/watch.go"
click node_maintenance "https://github.com/coreos/etcd/blob/main/server/etcdserver/api/v3rpc/maintenance.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_cache toneBlue
class node_embedded,node_grpc,node_protocol,node_auth,node_lease,node_watch,node_maintenance toneAmber
class node_server,node_raft,node_membership,node_peer toneMint
class node_kv,node_backend,node_wal,node_snapshots toneRose
class node_user,node_external toneIndigo
```

## Components

### Clients and tools

- [etcdctl](https://github.com/coreos/etcd/tree/main/etcdctl/ctlv3/command): `etcdctl/ctlv3/command`
- [Go client](https://github.com/coreos/etcd/blob/main/client/v3/client.go): `client/v3/client.go`
- [Watch cache](https://github.com/coreos/etcd/blob/main/cache/cache.go): `cache/cache.go`

### Serving and APIs

- [Embedded startup](https://github.com/coreos/etcd/blob/main/server/embed/etcd.go): `server/embed/etcd.go`
- [gRPC API](https://github.com/coreos/etcd/tree/main/server/etcdserver/api/v3rpc): `server/etcdserver/api/v3rpc`
- [API definitions](https://github.com/coreos/etcd/blob/main/api/etcdserverpb/rpc.proto): `api/etcdserverpb/rpc.proto`
- [Authentication](https://github.com/coreos/etcd/tree/main/server/auth): `server/auth`
- [Leases](https://github.com/coreos/etcd/tree/main/server/lease): `server/lease`
- [Watch API](https://github.com/coreos/etcd/blob/main/server/etcdserver/api/v3rpc/watch.go): `server/etcdserver/api/v3rpc/watch.go`
- [Maintenance API](https://github.com/coreos/etcd/blob/main/server/etcdserver/api/v3rpc/maintenance.go): `server/etcdserver/api/v3rpc/maintenance.go`

### Cluster and consensus

- [Etcd server](https://github.com/coreos/etcd/blob/main/server/etcdserver/server.go): `server/etcdserver/server.go`
- [Raft consensus](https://github.com/coreos/etcd/blob/main/server/etcdserver/raft.go): `server/etcdserver/raft.go`
- [Cluster membership](https://github.com/coreos/etcd/tree/main/server/etcdserver/api/membership): `server/etcdserver/api/membership`
- [Peer transport](https://github.com/coreos/etcd/tree/main/server/etcdserver/api/rafthttp): `server/etcdserver/api/rafthttp`

### Persistence and state

- [MVCC key-value](https://github.com/coreos/etcd/tree/main/server/storage/mvcc): `server/storage/mvcc`
- [Storage backend](https://github.com/coreos/etcd/tree/main/server/storage/backend): `server/storage/backend`
- [Raft WAL](https://github.com/coreos/etcd/tree/main/server/storage/wal): `server/storage/wal`
- [Snapshots](https://github.com/coreos/etcd/tree/main/server/etcdserver/api/snap): `server/etcdserver/api/snap`

### Other components

- **Operator or app**
- **Peer members**

## Connections

- Operator or app → etcdctl: runs commands (evidence: `README.md`)
- Operator or app → Go client: uses API (evidence: `README.md`)
- etcdctl → Go client: issues requests
- Go client → Embedded startup: sends gRPC (evidence: `README.md`)
- Embedded startup → Etcd server: starts (evidence: `server/embed/etcd.go`)
- Etcd server → gRPC API: serves requests
- gRPC API → API definitions: implements (evidence: `README.md`)
- Etcd server → Raft consensus: replicates state (evidence: `README.md`)
- Raft consensus → Peer transport: exchanges messages
- Peer transport → Peer members: communicates (evidence: `README.md`)
- Etcd server → Cluster membership: manages members
- Etcd server → MVCC key-value: applies requests
- MVCC key-value → Storage backend: persists state
- Raft consensus → Raft WAL: persists log
- Etcd server → Snapshots: creates snapshots
- gRPC API → Authentication: authorizes requests
- gRPC API → Leases: serves lease calls
- gRPC API → Watch API: serves watches
- gRPC API → Maintenance API: serves maintenance
- Go client → Watch cache: backs cache (evidence: `cache/cache.go`)
