Architecture·2 min read
The object model
Blobs, trees, commits and refs: the objects zev stores and how they link.
## Object types
A zev repository's history is built from three kinds of objects:
- **Blobs** — the content of a single file at a point in time.
- **Trees** — a directory listing: a flat set of (name, hash, size) entries pointing at blobs (or, for subdirectories, other trees).
- **Commits** — a pointer to a tree, a pointer to the previous commit (its parent), an author, a timestamp, and a message.
Every one of these is identified by a hash of its own content, as described in [Content-addressed storage](/docs/en/content-addressing).
## Local storage layout
On the client, objects live under `.zev/objects/`, each stored zstd-compressed, named by its SHA-256 hash. Refs — named pointers to commits, such as branch heads — live under `.zev/refs/`.
## Server storage layout
On the server, objects live on disk under a path sharded by the first two characters of their BLAKE3 hash (to keep any one directory from holding an unreasonable number of files), alongside PostgreSQL tables tracking which objects belong to which repository, and — for chunked files — a parallel `manifests` directory mapping a whole file's hash to its ordered list of chunk hashes.
## Push manifests
A push doesn't just upload objects; it uploads a manifest describing them — a JSON document listing, for every object in the pushed history, its `local_hash` (the client's SHA-256 identity) and the `server_hash` it was actually stored under (BLAKE3). This manifest is itself stored as a ref (`manifest/<branch>`), giving the server a durable, replayable record of exactly which objects a given push introduced and how their two identities correspond.
## Reconstruction, not replacement
The object model was extended twice during zev's development — once to add compression, once to add chunking — and in both cases the extension was built to be additive. Compression changed how bytes are stored on disk without changing what a hash identifies. Chunking added an alternate way to assemble a file's bytes without changing what the file's own hash is, or requiring any existing reader to know chunking exists at all.