# mah-bin/blobtrack architecture

> Architecture diagram of the GitHub repository mah-bin/blobtrack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mah-bin/blobtrack
- Repository: https://github.com/mah-bin/blobtrack

## Overview

blobtrack is a command-line version control system for large binary files. Its main workflow adds a file by streaming it through content-defined chunking, SHA-256 fingerprinting and compression, then deduplicating chunks in local storage. Commits record ordered chunk references and a Merkle root; checkout reconstructs files, while log and garbage collection manage history and stored objects. Push and pull synchronize missing chunks and commit metadata with another repository. The graph follows documented workflows and shown module references; some command-handler internals are only partially excerpted.

Main entry points: [`blobtrack/cli/commands.py`](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/cli/commands.py) (Command handlers), [`blobtrack/storage/remote_sync.py`](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/remote_sync.py) (Remote sync), [`blobtrack/storage/local_store.py`](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/local_store.py) (Chunk object store), [`blobtrack/cli/main.py`](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/cli/main.py) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interface"]
  node_cli_entry["CLI entry<br/>[main.py]"]
  node_handlers["Command handlers<br/>[commands.py]"]
end

subgraph group_engine["Content engine"]
  node_chunker["CDC chunker<br/>[chunker.py]"]
  node_fingerprinter["Chunk processor<br/>[hasher.py]"]
  node_compression["Compression<br/>[packer.py]"]
  node_merkle["Merkle trees<br/>[merkle_tree.py]"]
  node_differ["Tree differ<br/>[differ.py]"]
end

subgraph group_local["Local repository"]
  node_index[("Metadata index<br/>[index_db.py]")]
  node_objects[("Chunk object store<br/>[local_store.py]")]
end

subgraph group_sync["History and sync"]
  node_history[("Commit history<br/>[index_db.py]")]
  node_remote_sync["Remote sync<br/>[remote_sync.py]"]
end

node_user(("User"))
node_remote_repo[("Remote repository")]

node_user -->|"runs commands"| node_cli_entry
node_cli_entry -->|"dispatches to"| node_handlers
node_handlers -->|"streams files"| node_chunker
node_handlers -->|"processes chunks"| node_fingerprinter
node_fingerprinter -->|"compresses chunks"| node_compression
node_handlers -->|"decompresses chunks"| node_compression
node_handlers -->|"builds trees"| node_merkle
node_handlers -->|"computes deltas"| node_differ
node_differ -->|"walks trees"| node_merkle
node_handlers -->|"records metadata"| node_index
node_handlers -->|"stores chunks"| node_objects
node_handlers -->|"reads and writes commits"| node_history
node_handlers -->|"invokes sync"| node_remote_sync
node_remote_sync -->|"transfers chunks and commits"| node_remote_repo
node_remote_sync -->|"reads and writes chunks"| node_objects
node_remote_sync -->|"synchronizes metadata"| node_index
node_handlers -->|"restores files"| node_objects
node_handlers -->|"collects orphans"| node_objects

click node_cli_entry "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/cli/main.py"
click node_handlers "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/cli/commands.py"
click node_chunker "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/chunker.py"
click node_fingerprinter "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/hasher.py"
click node_compression "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/packer.py"
click node_merkle "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/merkle_tree.py"
click node_differ "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/differ.py"
click node_index "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/index_db.py"
click node_objects "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/local_store.py"
click node_history "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/index_db.py"
click node_remote_sync "https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/remote_sync.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_handlers,node_user toneBlue
class node_chunker,node_fingerprinter,node_compression,node_merkle,node_differ,node_remote_repo toneAmber
class node_index,node_objects toneMint
class node_history,node_remote_sync toneRose
```

## Components

### Command interface

- [CLI entry](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/cli/main.py): `blobtrack/cli/main.py`
- [Command handlers](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/cli/commands.py): `blobtrack/cli/commands.py`

### Content engine

- [CDC chunker](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/chunker.py): `blobtrack/core/chunker.py`
- [Chunk processor](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/hasher.py): `blobtrack/core/hasher.py`
- [Compression](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/packer.py): `blobtrack/core/packer.py`
- [Merkle trees](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/merkle_tree.py): `blobtrack/core/merkle_tree.py`
- [Tree differ](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/core/differ.py): `blobtrack/core/differ.py`

### Local repository

- [Metadata index](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/index_db.py): `blobtrack/storage/index_db.py`
- [Chunk object store](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/local_store.py): `blobtrack/storage/local_store.py`

### History and sync

- [Commit history](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/index_db.py): `blobtrack/storage/index_db.py`
- [Remote sync](https://github.com/mah-bin/blobtrack/blob/main/blobtrack/storage/remote_sync.py): `blobtrack/storage/remote_sync.py`

### Other components

- **User**
- **Remote repository**

## Connections

- User → CLI entry: runs commands (evidence: `blobtrack/cli/main.py`)
- CLI entry → Command handlers: dispatches to (evidence: `blobtrack/cli/main.py`)
- Command handlers → CDC chunker: streams files (evidence: `README.md`)
- Command handlers → Chunk processor: processes chunks (evidence: `README.md`)
- Chunk processor → Compression: compresses chunks (evidence: `blobtrack/core/hasher.py`)
- Command handlers → Compression: decompresses chunks (evidence: `README.md`)
- Command handlers → Merkle trees: builds trees (evidence: `blobtrack/cli/commands.py`)
- Command handlers → Tree differ: computes deltas (evidence: `blobtrack/cli/commands.py`)
- Tree differ → Merkle trees: walks trees (evidence: `blobtrack/core/differ.py`)
- Command handlers → Metadata index: records metadata (evidence: `blobtrack/cli/commands.py`)
- Command handlers → Chunk object store: stores chunks (evidence: `README.md`)
- Command handlers → Commit history: reads and writes commits (evidence: `README.md`)
- Command handlers → Remote sync: invokes sync (evidence: `blobtrack/cli/commands.py`)
- Remote sync → Remote repository: transfers chunks and commits (evidence: `blobtrack/storage/remote_sync.py`)
- Remote sync → Chunk object store: reads and writes chunks (evidence: `blobtrack/storage/remote_sync.py`)
- Remote sync → Metadata index: synchronizes metadata (evidence: `blobtrack/storage/remote_sync.py`)
- Command handlers → Chunk object store: restores files (evidence: `README.md`)
- Command handlers → Chunk object store: collects orphans (evidence: `README.md`)
