# neondatabase/neon architecture

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

- Interactive diagram: https://gitdiagram.com/neondatabase/neon
- Repository: https://github.com/neondatabase/neon

## Overview

Neon is a serverless PostgreSQL platform: clients connect to stateless PostgreSQL compute, while pageservers provide durable, branchable storage and safekeepers retain redundant WAL until pageservers process it. The tree also contains the proxy and local control-plane tooling, plus storage coordination and remote-storage implementations. The README documents the principal storage flow and local tenant/endpoint/branch workflow; sampled source confirms selected control-plane and pageserver internals. Several runtime links involving unsampled proxy and compute code remain unverified and are shown as dashed.

Main entry points: [`control_plane/src/local_env.rs`](https://github.com/neondatabase/neon/blob/main/control_plane/src/local_env.rs) (Local environment CLI), [`pageserver/src/tenant.rs`](https://github.com/neondatabase/neon/blob/main/pageserver/src/tenant.rs) (Pageserver), [`compute_tools/src/compute.rs`](https://github.com/neondatabase/neon/blob/main/compute_tools/src/compute.rs) (Compute node), [`safekeeper/src/wal_storage.rs`](https://github.com/neondatabase/neon/blob/main/safekeeper/src/wal_storage.rs) (Safekeeper WAL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client access"]
  node_proxy["Connection proxy<br/>[lib.rs]"]
end

subgraph group_compute["PostgreSQL compute"]
  node_compute_node["Compute node<br/>[compute.rs]"]
  node_compute_management["Compute management API<br/>[server.rs]"]
end

subgraph group_storage["Neon storage engine"]
  node_pageserver["Pageserver<br/>[tenant.rs]"]
  node_page_service["Page service<br/>[page_service.rs]"]
  node_timeline["Timeline storage<br/>[timeline.rs]"]
  node_storage_layers["Storage layers<br/>[storage_layer.rs]"]
  node_remote_storage["Remote storage<br/>[lib.rs]"]
  node_virtual_files["Virtual files<br/>[virtual_file.rs]"]
  node_io_engine["File I/O engine<br/>[io_engine.rs]"]
  node_safekeeper[("Safekeeper WAL<br/>[wal_storage.rs]")]
  node_broker["Storage broker<br/>[lib.rs]"]
end

subgraph group_operations["Control and operations"]
  node_storage_controller["Storage controller<br/>[service.rs]"]
  node_local_cli["Local environment CLI<br/>[local_env.rs]"]
  node_endpoint_storage["Endpoint object storage<br/>[app.rs]"]
end

node_client(("SQL client"))
node_cloud_storage[("Cloud object storage")]
node_postgresql["PostgreSQL server"]

node_client -.->|"connects through"| node_proxy
node_proxy -.->|"routes sessions"| node_compute_node
node_compute_node -->|"runs"| node_postgresql
node_compute_node -->|"uses storage"| node_pageserver
node_compute_node -->|"sends WAL"| node_safekeeper
node_safekeeper -->|"WAL processed by"| node_pageserver
node_pageserver -->|"uploads data"| node_cloud_storage
node_pageserver -->|"manages timelines"| node_timeline
node_timeline -->|"uses layers"| node_storage_layers
node_storage_layers -->|"performs file I/O"| node_virtual_files
node_virtual_files -->|"dispatches I/O"| node_io_engine
node_local_cli -->|"starts locally"| node_pageserver
node_local_cli -->|"starts locally"| node_safekeeper
node_local_cli -->|"starts locally"| node_broker
node_local_cli -->|"starts process"| node_endpoint_storage
node_storage_controller -->|"coordinates local setup"| node_local_cli

click node_proxy "https://github.com/neondatabase/neon/blob/main/proxy/src/lib.rs"
click node_compute_node "https://github.com/neondatabase/neon/blob/main/compute_tools/src/compute.rs"
click node_compute_management "https://github.com/neondatabase/neon/blob/main/compute_tools/src/http/server.rs"
click node_pageserver "https://github.com/neondatabase/neon/blob/main/pageserver/src/tenant.rs"
click node_page_service "https://github.com/neondatabase/neon/blob/main/pageserver/src/page_service.rs"
click node_timeline "https://github.com/neondatabase/neon/blob/main/pageserver/src/tenant/timeline.rs"
click node_storage_layers "https://github.com/neondatabase/neon/blob/main/pageserver/src/tenant/storage_layer.rs"
click node_remote_storage "https://github.com/neondatabase/neon/blob/main/libs/remote_storage/src/lib.rs"
click node_virtual_files "https://github.com/neondatabase/neon/blob/main/pageserver/src/virtual_file.rs"
click node_io_engine "https://github.com/neondatabase/neon/blob/main/pageserver/src/virtual_file/io_engine.rs"
click node_safekeeper "https://github.com/neondatabase/neon/blob/main/safekeeper/src/wal_storage.rs"
click node_broker "https://github.com/neondatabase/neon/blob/main/storage_broker/src/lib.rs"
click node_storage_controller "https://github.com/neondatabase/neon/blob/main/storage_controller/src/service.rs"
click node_local_cli "https://github.com/neondatabase/neon/blob/main/control_plane/src/local_env.rs"
click node_endpoint_storage "https://github.com/neondatabase/neon/blob/main/endpoint_storage/src/app.rs"

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_proxy,node_client toneBlue
class node_compute_node,node_compute_management,node_cloud_storage,node_postgresql toneAmber
class node_pageserver,node_page_service,node_timeline,node_storage_layers,node_remote_storage,node_virtual_files,node_io_engine,node_safekeeper,node_broker toneMint
class node_storage_controller,node_local_cli,node_endpoint_storage toneRose
```

## Components

### Client access

- [Connection proxy](https://github.com/neondatabase/neon/blob/main/proxy/src/lib.rs): `proxy/src/lib.rs`

### PostgreSQL compute

- [Compute node](https://github.com/neondatabase/neon/blob/main/compute_tools/src/compute.rs): `compute_tools/src/compute.rs`
- [Compute management API](https://github.com/neondatabase/neon/blob/main/compute_tools/src/http/server.rs): `compute_tools/src/http/server.rs`

### Neon storage engine

- [Pageserver](https://github.com/neondatabase/neon/blob/main/pageserver/src/tenant.rs): `pageserver/src/tenant.rs`
- [Page service](https://github.com/neondatabase/neon/blob/main/pageserver/src/page_service.rs): `pageserver/src/page_service.rs`
- [Timeline storage](https://github.com/neondatabase/neon/blob/main/pageserver/src/tenant/timeline.rs): `pageserver/src/tenant/timeline.rs`
- [Storage layers](https://github.com/neondatabase/neon/blob/main/pageserver/src/tenant/storage_layer.rs): `pageserver/src/tenant/storage_layer.rs`
- [Remote storage](https://github.com/neondatabase/neon/blob/main/libs/remote_storage/src/lib.rs): `libs/remote_storage/src/lib.rs`
- [Virtual files](https://github.com/neondatabase/neon/blob/main/pageserver/src/virtual_file.rs): `pageserver/src/virtual_file.rs`
- [File I/O engine](https://github.com/neondatabase/neon/blob/main/pageserver/src/virtual_file/io_engine.rs): `pageserver/src/virtual_file/io_engine.rs`
- [Safekeeper WAL](https://github.com/neondatabase/neon/blob/main/safekeeper/src/wal_storage.rs): `safekeeper/src/wal_storage.rs`
- [Storage broker](https://github.com/neondatabase/neon/blob/main/storage_broker/src/lib.rs): `storage_broker/src/lib.rs`

### Control and operations

- [Storage controller](https://github.com/neondatabase/neon/blob/main/storage_controller/src/service.rs): `storage_controller/src/service.rs`
- [Local environment CLI](https://github.com/neondatabase/neon/blob/main/control_plane/src/local_env.rs): `control_plane/src/local_env.rs`
- [Endpoint object storage](https://github.com/neondatabase/neon/blob/main/endpoint_storage/src/app.rs): `endpoint_storage/src/app.rs`

### Other components

- **SQL client**
- **Cloud object storage**
- **PostgreSQL server**

## Connections

- SQL client → Connection proxy: connects through
- Connection proxy → Compute node: routes sessions
- Compute node → PostgreSQL server: runs (evidence: `README.md`)
- Compute node → Pageserver: uses storage (evidence: `README.md`)
- Compute node → Safekeeper WAL: sends WAL (evidence: `README.md`)
- Safekeeper WAL → Pageserver: WAL processed by (evidence: `README.md`)
- Pageserver → Cloud object storage: uploads data (evidence: `README.md`)
- Pageserver → Timeline storage: manages timelines (evidence: `pageserver/src/tenant.rs`)
- Timeline storage → Storage layers: uses layers (evidence: `pageserver/src/tenant/timeline.rs`)
- Storage layers → Virtual files: performs file I/O (evidence: `pageserver/src/tenant/storage_layer.rs`)
- Virtual files → File I/O engine: dispatches I/O (evidence: `pageserver/src/virtual_file.rs`)
- Local environment CLI → Pageserver: starts locally (evidence: `control_plane/src/local_env.rs`)
- Local environment CLI → Safekeeper WAL: starts locally (evidence: `control_plane/src/local_env.rs`)
- Local environment CLI → Storage broker: starts locally (evidence: `control_plane/src/local_env.rs`)
- Local environment CLI → Endpoint object storage: starts process
- Storage controller → Local environment CLI: coordinates local setup
