Skip to content
~/docs/internals/architecture
DOCUMENTATION

Architecture

How KiteDB is structured internally

KiteDB is built as a layered system. Each layer has a specific job, and they work together to provide fast, reliable graph storage.

The Three Layers

Query Layer

Fluent API, type inference, schema validation
db.insert(user).values({...})

Graph Layer

Nodes, edges, traversal, transactions
createNode(), addEdge(), getNeighborsOut()

Storage Layer

Snapshot (CSR), Delta, WAL, Key Index
Memory-mapped files, crash recovery

Query Layer

This is what you interact with. It provides the Drizzle-style API with full TypeScript type inference. When you write db.insert(user).values(...), the query layer validates your schema, converts TypeScript types to storage types, and calls into the graph layer.

Graph Layer

Manages the graph abstraction: nodes with properties, edges between nodes, and traversals. Handles transaction boundaries and coordinates reads between the snapshot and delta.

Storage Layer

The foundation. Stores data in a format optimized for graph operations. The key insight here is the Snapshot + Delta model, which separates immutable historical data from pending changes.

What Happens When You Insert a Node

Let's trace through a simple insert:

typescript
await db.insert(user).values({ key: 'alice', name: 'Alice', age: 30 });
1

Query Layer

├Validates schema user has required properties
├Converts age: 30 → internal I64 type
└Calls graph layer: createNode(...)
2

Graph Layer

├Begins transaction (if not already in one)
├Allocates new NodeID (monotonic counter)
├Records in transaction state
└On commit → writes to WAL and Delta
3

Storage Layer

├WAL: Appends CREATE_NODE record (durability)
├Delta: Adds node to createdNodes map
└Later: Checkpoint merges into snapshot

What Happens When You Read

Reads merge data from two sources:

typescript
const alice = await db.get(user, 'alice');
1

Key Index Lookup

├Check delta.keyIndex (recent changes)
├If not found → check snapshot's hash-bucketed index
└Returns NodeID
2

Property Fetch

├Check delta.modifiedNodes for changes
├Fall back to snapshot for unchanged properties
└Merge and return combined result
Returns latest committed data

Why This Design

Design ChoiceBenefit
Snapshot + DeltaReads don't block writes. Snapshot is immutable, delta is small.
CSR format for edgesTraversals read contiguous memory. CPU cache loves this.
WAL for durabilityCommitted data survives crashes. Recovery is fast.
Single filePortable, atomic operations, simpler deployment.
Memory-mapped I/OOS handles caching. Zero-copy reads.

Next Steps

./edit --remote