> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> How versioned file systems and repositories store metadata, deliver file content, merge changes, and expose operational state.
This page is a deep dive. You do not need it for day-to-day use. Start with [Versioned File Systems](/filesystems/introduction) or [Git Repositories](/git/introduction) first. File systems and repositories share the mount client and product concepts but store history in [two different engines](#two-storage-engines-one-mount-client).
## Overview
Tensorlake separates metadata from file content.
* The **control plane** stores history metadata (for repositories that's Git commits, refs, branches, and private workspace WAL checkpoints; for file systems it's native content-addressed snapshots and per-session checkpoint journals), plus sessions, workspaces, and operation history.
* The **data plane** stores file content in blob storage (Git objects for repositories, content-addressed blobs for file systems).
* Mounts resolve metadata through the control plane and fetch file content lazily from the data plane.
This split keeps session creation, snapshot listing, and history fast even when a file system or repository is large.
```mermaid theme={null}
graph TD
Client["CLI / API"] --> Meta
subgraph CP["Control Plane"]
direction LR
Meta["Metadata Store
native snapshots · journals · Git refs · sessions"]
Reconcile["Reconcile / Merge
change-set rebase (fs) · 3-way merge (git)"]
Bg["Background Maintenance
optimization, dedup, retention, GC"]
end
subgraph DP["Data Plane"]
Blob["Blob Store
file content"]
end
Meta --> Reconcile
Bg -.-> Blob
Meta -- "resolves ref to tree" --> Mount["File System Mount"]
Blob -- "lazy, parallel fetch" --> Mount
Mount --> S1["Sandbox"]
Mount --> S2["Sandbox"]
Mount --> S3["Sandbox"]
```
## Two storage engines, one mount client
File systems and repositories share the mount/overlay client, crash-safe local journal, and lazy content delivery, but they store and publish history through **different engines**:
* **Repositories** are Git. History is Git commits, refs, and branches; content is packed into Git objects; they speak Git smart-HTTP so `git clone`/`push` work.
* **File systems** run the native snapshot engine. History is immutable content-addressed checkpoints and snapshots (not Git commits); file content is deduplicated and packed into content-addressed blobs; and a per-session **checkpoint journal** is the crash-safe replication path into the shared timeline. File systems have no Git access: no commits, refs, branches, packs, or Git wire protocol.
A session or workspace is metadata, not a full copy. It records what it belongs to, the point it started from, and its durable WAL or snapshot chain. A Git read-only mount creates no workspace; a writable Git workspace is created lazily when its first remote WAL checkpoint arrives. Saving uploads only changed content. Optimization, deduplication, retention, and garbage collection run in the background so agents never wait on storage maintenance.
## One local journal, two product surfaces
Writable file-system and repository mounts share one crash-safe client pipeline:
```mermaid theme={null}
graph LR
W["File writes"] --> J["Local journal
crash recovery"]
J --> U["Upload changed content"]
U --> C["Server WAL checkpoint
durable replication boundary"]
C --> F{"Surface"}
F -->|"fs autosave"| H["Shared file-system timeline"]
F -->|"tl git snapshot"| G["Workspace Git commit"]
G -->|"tl git promote"| B["Branch"]
C --> P["Prune confirmed local generations"]
```
The difference is publication policy. On `tl fs`, the server verifies, orders, and applies each autosave checkpoint to the shared drive before acknowledging it; `tl fs snapshot` adds a permanent retention point. On `tl git`, autosave checkpoints remain private workspace WAL: they create neither a Git commit nor a branch update. `tl git snapshot` materializes the current WAL as a workspace commit, and `tl git promote` deliberately lands it on a branch.
## Content Delivery
Mounting a repository or file system does not copy it into the sandbox. The mount resolves the tree, then fetches file content lazily as processes read paths.
That means:
* Large repositories can mount quickly.
* A sandbox only downloads paths it actually reads.
* Many sandboxes can mount the same repository without a single shared serving path becoming the bottleneck.
Following read-only mounts add branch tracking. When the followed branch moves, Tensorlake compares the old and new commits and invalidates only changed paths. Unchanged files keep their warm page cache.
## Reconciling concurrent writes
The two engines reconcile concurrent writes differently, because they model history differently.
**File systems have one linear timeline.** When checkpoints race, the server orders them and rebases each update's changed paths onto the current head before acknowledging it. Cost is proportional to changed paths, not file-system size. Disjoint paths merge automatically; two writers on the same path are last-writer-wins: the later ordered update's version of that file sticks, silently. There is no three-way merge and no conflict marker on a file system, because a single timeline has nothing to diverge from. See [Concurrent Writes](/filesystems/concurrent-writes).
**Repositories can have divergent branches**, so they use a server-side three-way merge engine, verified against Git's merge behavior, for promote, `git merge`, and rebase. It compares the common ancestor, the target branch, and the workspace, resolving non-overlapping edits automatically and surfacing genuine conflicts. `tl git sync` has a narrower role: it refreshes or switches a read-only or snapshot-free view, carrying its WAL tail forward, and refuses to rewrite an established workspace snapshot chain. Two conflict behaviors apply on the repository surface: **Fail** (the default for promotion: nothing lands, a structured conflict report is returned) and **Materialize** (writes Git conflict markers plus a queryable conflict record). Both preserve the losing content in Git history.
## Promotion
Promotion is the repository surface's path through the merge engine. It first materializes any dirty workspace WAL, then lands the workspace as one squashed commit. See [Repository Mounts](/git/workspace-mounts) for the workflow. File systems have no promote step: replicated autosaves advance the shared timeline automatically, while snapshots make selected points permanent.
## Observability
Durable file-system and repository state is queryable through the API and available to the control plane:
* Which workspaces are live.
* Which are detached and resumable.
* Which durable WAL checkpoints and snapshots exist.
* Which principal created each snapshot.
* Which paths changed.
For file systems, the durable record is the single timeline's checkpoint and snapshot history. For repositories, branch activity is also recorded: pushes, promotions, rebases, merges, and materialized conflict records. Mount heartbeats expose liveness, but the unsealed tail of edits remains in the sandbox's local journal until autosave. The control plane does not observe every in-progress file edit.
Detached Git workspaces are collected by lifecycle tier. An actively mounted workspace is retained; a WAL-only detached workspace defaults to 48 hours, and a detached workspace with snapshots defaults to 14 days. The deployment configuration controls these periods.
File systems, mounts, local journals, autosave checkpoints, snapshots, and publishing.
Mount, autosave, create permanent snapshots, inspect status, and clean up.
Clone, branch, commit, merge, push, and fetch with plain Git.
Run agents in isolated sandboxes and mount file systems into them.