# zkat/cacache-rs architecture

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

- Interactive diagram: https://gitdiagram.com/zkat/cacache-rs
- Repository: https://github.com/zkat/cacache-rs

## Overview

cacache is a concurrent, content-addressable disk-cache library. Applications write keyed data, which is integrity-hashed and stored as content, with key metadata recorded in an index; reads resolve the key and verify the stored content. The library also supports hash-based access, streaming large files, deletion, listing, and optional symlink-based ingestion. The graph reflects documented APIs and relationships visible in the supplied excerpts or SOURCE INDEX; some implementation details of unsampled modules are not shown.

Main entry points: [`src/index.rs`](https://github.com/zkat/cacache-rs/blob/main/src/index.rs) (Key Index), [`src/content/path.rs`](https://github.com/zkat/cacache-rs/blob/main/src/content/path.rs) (Content Addressing), [`src/put.rs`](https://github.com/zkat/cacache-rs/blob/main/src/put.rs) (Write API), [`src/get.rs`](https://github.com/zkat/cacache-rs/blob/main/src/get.rs) (Read API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Cache APIs"]
  node_write["Write API<br/>[put.rs]"]
  node_read["Read API<br/>[get.rs]"]
  node_link["Link API<br/>[linkto.rs]"]
  node_remove["Remove API<br/>[rm.rs]"]
  node_listing["List API<br/>[ls.rs]"]
end

subgraph group_content["Content Handling"]
  node_writer["Content Writer<br/>[write.rs]"]
  node_reader["Content Reader<br/>[read.rs]"]
  node_linker["File Linker<br/>[linkto.rs]"]
  node_content_rm["Content Removal<br/>[rm.rs]"]
  node_content_path["Content Addressing<br/>[path.rs]"]
end

subgraph group_storage["Disk Storage"]
  node_index[("Key Index<br/>[index.rs]")]
  node_content_store[("Content Store<br/>[write.rs]")]
end

subgraph group_support["Runtime Support"]
  node_async["Async Runtime<br/>[async_lib.rs]"]
  node_errors["Error Reporting<br/>[errors.rs]"]
end

node_caller(("Application"))

node_caller -->|"writes key"| node_write
node_caller -->|"reads key"| node_read
node_caller -->|"removes entries"| node_remove
node_caller -.->|"links file"| node_link
node_write -->|"writes content"| node_writer
node_write -->|"records metadata"| node_index
node_writer -->|"resolves path"| node_content_path
node_read -->|"finds key"| node_index
node_read -->|"reads verified content"| node_reader
node_reader -->|"resolves path"| node_content_path
node_link -->|"links target"| node_linker
node_link -->|"records metadata"| node_index
node_linker -->|"resolves path"| node_content_path
node_remove -->|"removes content"| node_content_rm
node_remove -->|"updates index"| node_index
node_content_rm -->|"resolves path"| node_content_path
node_listing -->|"lists keys"| node_index
node_index -->|"resolves content"| node_content_path
node_writer -->|"uses filesystem"| node_async
node_reader -->|"uses filesystem"| node_async
node_linker -->|"uses filesystem"| node_async
node_content_rm -->|"removes asynchronously"| node_async
node_write -->|"returns errors"| node_errors
node_read -->|"returns errors"| node_errors

click node_write "https://github.com/zkat/cacache-rs/blob/main/src/put.rs"
click node_read "https://github.com/zkat/cacache-rs/blob/main/src/get.rs"
click node_link "https://github.com/zkat/cacache-rs/blob/main/src/linkto.rs"
click node_remove "https://github.com/zkat/cacache-rs/blob/main/src/rm.rs"
click node_listing "https://github.com/zkat/cacache-rs/blob/main/src/ls.rs"
click node_writer "https://github.com/zkat/cacache-rs/blob/main/src/content/write.rs"
click node_reader "https://github.com/zkat/cacache-rs/blob/main/src/content/read.rs"
click node_linker "https://github.com/zkat/cacache-rs/blob/main/src/content/linkto.rs"
click node_content_rm "https://github.com/zkat/cacache-rs/blob/main/src/content/rm.rs"
click node_content_path "https://github.com/zkat/cacache-rs/blob/main/src/content/path.rs"
click node_index "https://github.com/zkat/cacache-rs/blob/main/src/index.rs"
click node_content_store "https://github.com/zkat/cacache-rs/blob/main/src/content/write.rs"
click node_async "https://github.com/zkat/cacache-rs/blob/main/src/async_lib.rs"
click node_errors "https://github.com/zkat/cacache-rs/blob/main/src/errors.rs"

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_write,node_read,node_link,node_remove,node_listing toneBlue
class node_writer,node_reader,node_linker,node_content_rm,node_content_path toneAmber
class node_index,node_content_store toneMint
class node_async,node_errors toneRose
class node_caller toneIndigo
```

## Components

### Cache APIs

- [Write API](https://github.com/zkat/cacache-rs/blob/main/src/put.rs): `src/put.rs`
- [Read API](https://github.com/zkat/cacache-rs/blob/main/src/get.rs): `src/get.rs`
- [Link API](https://github.com/zkat/cacache-rs/blob/main/src/linkto.rs): `src/linkto.rs`
- [Remove API](https://github.com/zkat/cacache-rs/blob/main/src/rm.rs): `src/rm.rs`
- [List API](https://github.com/zkat/cacache-rs/blob/main/src/ls.rs): `src/ls.rs`

### Content Handling

- [Content Writer](https://github.com/zkat/cacache-rs/blob/main/src/content/write.rs): `src/content/write.rs`
- [Content Reader](https://github.com/zkat/cacache-rs/blob/main/src/content/read.rs): `src/content/read.rs`
- [File Linker](https://github.com/zkat/cacache-rs/blob/main/src/content/linkto.rs): `src/content/linkto.rs`
- [Content Removal](https://github.com/zkat/cacache-rs/blob/main/src/content/rm.rs): `src/content/rm.rs`
- [Content Addressing](https://github.com/zkat/cacache-rs/blob/main/src/content/path.rs): `src/content/path.rs`

### Disk Storage

- [Key Index](https://github.com/zkat/cacache-rs/blob/main/src/index.rs): `src/index.rs`
- [Content Store](https://github.com/zkat/cacache-rs/blob/main/src/content/write.rs): `src/content/write.rs`

### Runtime Support

- [Async Runtime](https://github.com/zkat/cacache-rs/blob/main/src/async_lib.rs): `src/async_lib.rs`
- [Error Reporting](https://github.com/zkat/cacache-rs/blob/main/src/errors.rs): `src/errors.rs`

### Other components

- **Application**

## Connections

- Application → Write API: writes key (evidence: `README.md`)
- Application → Read API: reads key (evidence: `README.md`)
- Application → Remove API: removes entries (evidence: `README.md`)
- Application → Link API: links file (evidence: `README.md`)
- Write API → Content Writer: writes content (evidence: `src/put.rs`)
- Write API → Key Index: records metadata (evidence: `src/put.rs`)
- Content Writer → Content Addressing: resolves path (evidence: `src/content/write.rs`)
- Read API → Key Index: finds key (evidence: `src/get.rs`)
- Read API → Content Reader: reads verified content (evidence: `src/get.rs`)
- Content Reader → Content Addressing: resolves path (evidence: `src/content/read.rs`)
- Link API → File Linker: links target (evidence: `src/linkto.rs`)
- Link API → Key Index: records metadata (evidence: `src/linkto.rs`)
- File Linker → Content Addressing: resolves path (evidence: `src/content/linkto.rs`)
- Remove API → Content Removal: removes content (evidence: `src/rm.rs`)
- Remove API → Key Index: updates index (evidence: `src/rm.rs`)
- Content Removal → Content Addressing: resolves path (evidence: `src/content/rm.rs`)
- List API → Key Index: lists keys (evidence: `src/ls.rs`)
- Key Index → Content Addressing: resolves content (evidence: `src/index.rs`)
- Content Writer → Async Runtime: uses filesystem (evidence: `src/content/write.rs`)
- Content Reader → Async Runtime: uses filesystem (evidence: `src/content/read.rs`)
- File Linker → Async Runtime: uses filesystem (evidence: `src/content/linkto.rs`)
- Content Removal → Async Runtime: removes asynchronously (evidence: `src/content/rm.rs`)
- Write API → Error Reporting: returns errors (evidence: `src/put.rs`)
- Read API → Error Reporting: returns errors (evidence: `src/get.rs`)
