> ## 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 Git-backed file systems store metadata, deliver file content, merge workspaces, and expose operational state.

This page is a deep dive. You do not need it for day-to-day use. Start with [Git-backed File Systems](/filesystems/introduction), [Core Concepts](/filesystems/core-concepts), or [File System Mounts](/filesystems/filesystem-mounts) first.

## Overview

Tensorlake separates repository metadata from file content.

* The **control plane** stores commits, refs, branches, workspaces, merge state, and operation history.
* The **data plane** stores file content in blob storage.
* Mounts resolve metadata through the control plane and fetch file content lazily from the data plane.

This split keeps workspace creation, branch resolution, and snapshot listing fast even when repositories are large.

```mermaid theme={null}
graph TD
    Client["CLI / API"] --> Meta
    subgraph CP["Control Plane"]
      direction LR
      Meta["Metadata Store<br/><small>commits, refs, branches, workspaces</small>"]
      Merge["Merge Engine<br/><small>three-way merge, conflict resolution</small>"]
      Bg["Background Maintenance<br/><small>optimization, dedup, GC</small>"]
    end
    subgraph DP["Data Plane"]
      Blob["Blob Store<br/><small>file content</small>"]
    end
    Meta --> Merge
    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"]
```

## Metadata and Storage

A workspace is metadata, not a full repository copy. It records:

* The repository it belongs to.
* The branch or commit it forked from.
* The workspace snapshot chain.

Creating a workspace writes a small metadata record. Snapshotting appends a commit to that workspace chain and uploads only changed content. Repository optimization, deduplication, and garbage collection run in the background so agents do not wait on storage maintenance.

## Content Delivery

Mounting a repository does not copy the repository 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.

## Merge Engine

Every divergent-history operation uses the same server-side merge engine:

* Promoting a workspace to a branch.
* Merging one branch into another.
* Auto-publishing snapshots from a shared read-write workspace.

The merge engine uses standard three-way merge semantics and is verified against Git's merge behavior. It compares the common ancestor, the target branch, and the workspace or source branch.

Cost is proportional to changed paths, not total repository size:

* If only one side changed a path, that change wins.
* If both sides made the same change, the path resolves automatically.
* If both sides edited different regions of a text file, the text merge resolves automatically.
* If both sides conflict, the result depends on conflict policy.

## Conflict Policies

Tensorlake uses two main conflict behaviors.

**Fail** is the default for manual promotion. Nothing lands on the target branch. The operation returns a structured conflict report. The agent resolves the conflict in the workspace, snapshots again, and promotes again.

**Materialize** is the default for shared read-write branches. The merge lands with standard Git conflict markers in conflicted files. The commit also carries a structured conflict record so tooling can query conflicts without parsing file contents.

Both policies preserve the losing content in Git history.

## Promotion

Promotion is the user-facing path through the merge engine. A workspace can land as one squashed commit or preserve each workspace snapshot as branch history. See [Writable Workspaces](/filesystems/writable-workspaces) for the workflow.

## Observability

Every mounted file system and workspace is queryable through the API and visible in the dashboard:

* Which workspaces are live.
* Which are detached and resumable.
* Which snapshots exist.
* Which principal created each snapshot.
* Which paths changed.

Branch activity is also recorded: pushes, promotions, shared read-write reconciliations, merges, and materialized conflict records. This gives automation enough state to manage sandbox fleets based on file-system activity.

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book-open" href="/filesystems/core-concepts">
    Repositories, workspaces, mounts, snapshots, promotion, and mount modes.
  </Card>

  <Card title="File System Mounts" icon="folder-tree" href="/filesystems/filesystem-mounts">
    Mount, snapshot, promote, inspect status, roll back, and clean up.
  </Card>

  <Card title="Git Repositories" icon="code-commit" href="/filesystems/git-repositories">
    Clone, branch, commit, merge, push, and fetch with plain Git.
  </Card>

  <Card title="Sandboxes" icon="container" href="/sandboxes/introduction">
    Run agents in isolated sandboxes and mount file systems into them.
  </Card>
</CardGroup>