Primitives

The Neon codebase has a small set of foundational concepts that show up in almost every subsystem. They are the vocabulary for everything else: tenants, timelines, LSNs, layers, shards, branches. Understanding them once unlocks reading a great deal of code at a higher level.

This section breaks them down. The brief glossary is in overview/glossary; these pages go deeper.

Pages

• Tenant and timeline — the unit of isolation and the unit of WAL history.
• LSN and WAL — the byte-offset clock, and the durability stream.
• Layers — the pageserver's storage atom.
• Branches — copy-on-write timelines with shared ancestors.

Why "primitives" not "domain models"

These types are not just data structures — they are the assumptions the entire system is built on. The pageserver's storage layout, the safekeeper's consensus, the compute's GetPage@LSN calls, the storage controller's placement: all of them are organized around the same (tenant, timeline, lsn) tuple. If you change one of these primitives you almost certainly have to change several services.

Where they live in code

Concept	Type	Module
Tenant id	TenantId	libs/utils/src/id.rs
Timeline id	TimelineId	libs/utils/src/id.rs
Shard identity	ShardIdentity	libs/pageserver_api/src/shard.rs
LSN	Lsn	libs/utils/src/lsn.rs
Layer	Layer trait	pageserver/src/tenant/storage_layer.rs
Branch	(no dedicated type — "branch" is a name for a Timeline)	pageserver/src/tenant/timeline.rs
Generation	Generation	libs/pageserver_api/src/control_api.rs

The libs/utils/src/id.rs and libs/utils/src/lsn.rs files are short, well-commented, and a good place to start when first reading the codebase.