# awolverp/cachebox architecture

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

- Interactive diagram: https://gitdiagram.com/awolverp/cachebox
- Repository: https://github.com/awolverp/cachebox

## Overview

Cachebox exposes Python caching classes and a decorator, with Rust implementations providing thread-safe cache operations and eviction policies. The principal workflow is Python code selecting a cache, performing dictionary-like operations or using the decorator, and receiving cached values; policy logic governs lookup and eviction. The graph also shows the shared hash table and internal support layers. Some links rely on the SOURCE INDEX or README rather than complete source excerpts, so uncertain implementation details are omitted.

Main entry points: [`cachebox/_cachebox.py`](https://github.com/awolverp/cachebox/blob/main/cachebox/_cachebox.py) (Rust extension API), [`src/pyclasses/base.rs`](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/base.rs) (Base cache type), [`src/policies/traits.rs`](https://github.com/awolverp/cachebox/blob/main/src/policies/traits.rs) (Policy interfaces), [`src/policies/lfupolicy.rs`](https://github.com/awolverp/cachebox/blob/main/src/policies/lfupolicy.rs) (LFU policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python API"]
  node_facade["Python exports<br/>[__init__.py]"]
  node_extension["Rust extension API<br/>[_cachebox.py]"]
  node_decorators["Cached wrappers<br/>[_wrappers.py]"]
  node_utilities["Python utilities<br/>[utils.py]"]
end

subgraph group_cache["Cache classes"]
  node_base["Base cache type<br/>[base.rs]"]
  node_cache_api["Generic cache<br/>[cache.rs]"]
  node_fifo_cache["FIFO cache<br/>[fifocache.rs]"]
  node_lfu_cache["LFU cache<br/>[lfucache.rs]"]
  node_lru_cache["LRU cache<br/>[lrucache.rs]"]
  node_rr_cache["Random replacement<br/>[rrcache.rs]"]
  node_ttl_cache["TTL cache<br/>[ttlcache.rs]"]
  node_vttl_cache["Variable TTL cache<br/>[vttlcache.rs]"]
end

subgraph group_policies["Eviction policies"]
  node_policy_traits["Policy interfaces<br/>[traits.rs]"]
  node_policy_common["Shared policy logic<br/>[common.rs]"]
  node_policy_wrapped["Common operations<br/>[wrapped.rs]"]
  node_policy_fifo["FIFO policy<br/>[fifopolicy.rs]"]
  node_policy_lfu["LFU policy<br/>[lfupolicy.rs]"]
  node_policy_lru["LRU policy<br/>[lrupolicy.rs]"]
  node_policy_ttl["TTL policy<br/>[ttlpolicy.rs]"]
  node_policy_vttl["Variable TTL policy<br/>[vttlpolicy.rs]"]
  node_other_policies["Other policies"]
end

subgraph group_internals["Rust internals"]
  node_table["SwissTable storage<br/>[raw.rs]"]
  node_lazy_heap["Lazy heap<br/>[lazyheap.rs]"]
  node_linked_list["Linked list<br/>[linked_list.rs]"]
  node_once_init["Thread-safe init<br/>[onceinit.rs]"]
  node_pickle["Pickle helpers<br/>[pickle.rs]"]
  node_aliases["Python object aliases<br/>[alias.rs]"]
  node_internal_utils["Runtime utilities<br/>[utils.rs]"]
end

node_user(("Python application"))

node_user -->|"imports"| node_facade
node_facade -->|"exports"| node_extension
node_facade -->|"exports"| node_decorators
node_facade -->|"imports"| node_utilities
node_user -->|"decorates functions"| node_decorators
node_extension -->|"exposes classes"| node_cache_api
node_extension -->|"exposes classes"| node_fifo_cache
node_extension -->|"exposes classes"| node_lfu_cache
node_extension -->|"exposes classes"| node_lru_cache
node_extension -->|"exposes classes"| node_rr_cache
node_extension -->|"exposes classes"| node_ttl_cache
node_extension -->|"exposes classes"| node_vttl_cache
node_cache_api -->|"uses base type"| node_base
node_fifo_cache -->|"uses base type"| node_base
node_lfu_cache -->|"uses base type"| node_base
node_lru_cache -->|"uses base type"| node_base
node_rr_cache -->|"uses base type"| node_base
node_ttl_cache -->|"uses base type"| node_base
node_vttl_cache -->|"uses base type"| node_base
node_cache_api -->|"uses operations"| node_policy_wrapped
node_fifo_cache -->|"uses policy"| node_policy_fifo
node_lfu_cache -->|"uses policy"| node_policy_lfu
node_lru_cache -->|"uses policy"| node_policy_lru
node_rr_cache -->|"uses policy"| node_other_policies
node_ttl_cache -->|"uses policy"| node_policy_ttl
node_vttl_cache -->|"uses policy"| node_policy_vttl
node_policy_fifo -->|"implements"| node_policy_traits
node_policy_lfu -->|"implements"| node_policy_traits
node_policy_lru -->|"implements"| node_policy_traits
node_policy_ttl -->|"implements"| node_policy_traits
node_policy_vttl -->|"implements"| node_policy_traits
node_policy_fifo -->|"uses helpers"| node_policy_common
node_policy_lfu -->|"uses helpers"| node_policy_common
node_policy_lru -->|"uses helpers"| node_policy_common
node_policy_ttl -->|"uses helpers"| node_policy_common
node_policy_vttl -->|"uses helpers"| node_policy_common
node_policy_wrapped -->|"wraps policies"| node_policy_traits
node_policy_lfu -->|"uses heap"| node_lazy_heap
node_policy_vttl -->|"uses heap"| node_lazy_heap
node_policy_lru -->|"uses list"| node_linked_list
node_policy_fifo -->|"uses table"| node_table
node_policy_lfu -->|"uses table"| node_table
node_policy_lru -->|"uses table"| node_table
node_policy_ttl -->|"uses table"| node_table
node_policy_vttl -->|"uses table"| node_table
node_cache_api -->|"initializes through"| node_once_init
node_lfu_cache -->|"initializes through"| node_once_init
node_ttl_cache -->|"initializes through"| node_once_init

click node_facade "https://github.com/awolverp/cachebox/blob/main/cachebox/__init__.py"
click node_extension "https://github.com/awolverp/cachebox/blob/main/cachebox/_cachebox.py"
click node_decorators "https://github.com/awolverp/cachebox/blob/main/cachebox/_wrappers.py"
click node_utilities "https://github.com/awolverp/cachebox/blob/main/cachebox/utils.py"
click node_base "https://github.com/awolverp/cachebox/blob/main/src/pyclasses/base.rs"
click node_cache_api "https://github.com/awolverp/cachebox/blob/main/src/pyclasses/cache.rs"
click node_fifo_cache "https://github.com/awolverp/cachebox/blob/main/src/pyclasses/fifocache.rs"
click node_lfu_cache "https://github.com/awolverp/cachebox/blob/main/src/pyclasses/lfucache.rs"
click node_lru_cache "https://github.com/awolverp/cachebox/blob/main/src/pyclasses/lrucache.rs"
click node_rr_cache "https://github.com/awolverp/cachebox/blob/main/src/pyclasses/rrcache.rs"
click node_ttl_cache "https://github.com/awolverp/cachebox/blob/main/src/pyclasses/ttlcache.rs"
click node_vttl_cache "https://github.com/awolverp/cachebox/blob/main/src/pyclasses/vttlcache.rs"
click node_policy_traits "https://github.com/awolverp/cachebox/blob/main/src/policies/traits.rs"
click node_policy_common "https://github.com/awolverp/cachebox/blob/main/src/policies/common.rs"
click node_policy_wrapped "https://github.com/awolverp/cachebox/blob/main/src/policies/wrapped.rs"
click node_policy_fifo "https://github.com/awolverp/cachebox/blob/main/src/policies/fifopolicy.rs"
click node_policy_lfu "https://github.com/awolverp/cachebox/blob/main/src/policies/lfupolicy.rs"
click node_policy_lru "https://github.com/awolverp/cachebox/blob/main/src/policies/lrupolicy.rs"
click node_policy_ttl "https://github.com/awolverp/cachebox/blob/main/src/policies/ttlpolicy.rs"
click node_policy_vttl "https://github.com/awolverp/cachebox/blob/main/src/policies/vttlpolicy.rs"
click node_other_policies "https://github.com/awolverp/cachebox/tree/main/src/policies"
click node_table "https://github.com/awolverp/cachebox/blob/main/src/hashbrown/raw.rs"
click node_lazy_heap "https://github.com/awolverp/cachebox/blob/main/src/internal/lazyheap.rs"
click node_linked_list "https://github.com/awolverp/cachebox/blob/main/src/internal/linked_list.rs"
click node_once_init "https://github.com/awolverp/cachebox/blob/main/src/internal/onceinit.rs"
click node_pickle "https://github.com/awolverp/cachebox/blob/main/src/internal/pickle.rs"
click node_aliases "https://github.com/awolverp/cachebox/blob/main/src/internal/alias.rs"
click node_internal_utils "https://github.com/awolverp/cachebox/blob/main/src/internal/utils.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_facade,node_extension,node_decorators,node_utilities toneBlue
class node_base,node_cache_api,node_fifo_cache,node_lfu_cache,node_lru_cache,node_rr_cache,node_ttl_cache,node_vttl_cache toneAmber
class node_policy_traits,node_policy_common,node_policy_wrapped,node_policy_fifo,node_policy_lfu,node_policy_lru,node_policy_ttl,node_policy_vttl,node_other_policies toneMint
class node_table,node_lazy_heap,node_linked_list,node_once_init,node_pickle,node_aliases,node_internal_utils toneRose
class node_user toneIndigo
```

## Components

### Python API

- [Python exports](https://github.com/awolverp/cachebox/blob/main/cachebox/__init__.py): `cachebox/__init__.py`
- [Rust extension API](https://github.com/awolverp/cachebox/blob/main/cachebox/_cachebox.py): `cachebox/_cachebox.py`
- [Cached wrappers](https://github.com/awolverp/cachebox/blob/main/cachebox/_wrappers.py): `cachebox/_wrappers.py`
- [Python utilities](https://github.com/awolverp/cachebox/blob/main/cachebox/utils.py): `cachebox/utils.py`

### Cache classes

- [Base cache type](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/base.rs): `src/pyclasses/base.rs`
- [Generic cache](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/cache.rs): `src/pyclasses/cache.rs`
- [FIFO cache](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/fifocache.rs): `src/pyclasses/fifocache.rs`
- [LFU cache](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/lfucache.rs): `src/pyclasses/lfucache.rs`
- [LRU cache](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/lrucache.rs): `src/pyclasses/lrucache.rs`
- [Random replacement](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/rrcache.rs): `src/pyclasses/rrcache.rs`
- [TTL cache](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/ttlcache.rs): `src/pyclasses/ttlcache.rs`
- [Variable TTL cache](https://github.com/awolverp/cachebox/blob/main/src/pyclasses/vttlcache.rs): `src/pyclasses/vttlcache.rs`

### Eviction policies

- [Policy interfaces](https://github.com/awolverp/cachebox/blob/main/src/policies/traits.rs): `src/policies/traits.rs`
- [Shared policy logic](https://github.com/awolverp/cachebox/blob/main/src/policies/common.rs): `src/policies/common.rs`
- [Common operations](https://github.com/awolverp/cachebox/blob/main/src/policies/wrapped.rs): `src/policies/wrapped.rs`
- [FIFO policy](https://github.com/awolverp/cachebox/blob/main/src/policies/fifopolicy.rs): `src/policies/fifopolicy.rs`
- [LFU policy](https://github.com/awolverp/cachebox/blob/main/src/policies/lfupolicy.rs): `src/policies/lfupolicy.rs`
- [LRU policy](https://github.com/awolverp/cachebox/blob/main/src/policies/lrupolicy.rs): `src/policies/lrupolicy.rs`
- [TTL policy](https://github.com/awolverp/cachebox/blob/main/src/policies/ttlpolicy.rs): `src/policies/ttlpolicy.rs`
- [Variable TTL policy](https://github.com/awolverp/cachebox/blob/main/src/policies/vttlpolicy.rs): `src/policies/vttlpolicy.rs`
- [Other policies](https://github.com/awolverp/cachebox/tree/main/src/policies): `src/policies`

### Rust internals

- [SwissTable storage](https://github.com/awolverp/cachebox/blob/main/src/hashbrown/raw.rs): `src/hashbrown/raw.rs`
- [Lazy heap](https://github.com/awolverp/cachebox/blob/main/src/internal/lazyheap.rs): `src/internal/lazyheap.rs`
- [Linked list](https://github.com/awolverp/cachebox/blob/main/src/internal/linked_list.rs): `src/internal/linked_list.rs`
- [Thread-safe init](https://github.com/awolverp/cachebox/blob/main/src/internal/onceinit.rs): `src/internal/onceinit.rs`
- [Pickle helpers](https://github.com/awolverp/cachebox/blob/main/src/internal/pickle.rs): `src/internal/pickle.rs`
- [Python object aliases](https://github.com/awolverp/cachebox/blob/main/src/internal/alias.rs): `src/internal/alias.rs`
- [Runtime utilities](https://github.com/awolverp/cachebox/blob/main/src/internal/utils.rs): `src/internal/utils.rs`

### Other components

- **Python application**

## Connections

- Python application → Python exports: imports
- Python exports → Rust extension API: exports (evidence: `cachebox/__init__.py`)
- Python exports → Cached wrappers: exports (evidence: `cachebox/__init__.py`)
- Python exports → Python utilities: imports (evidence: `cachebox/__init__.py`)
- Python application → Cached wrappers: decorates functions
- Rust extension API → Generic cache: exposes classes
- Rust extension API → FIFO cache: exposes classes
- Rust extension API → LFU cache: exposes classes
- Rust extension API → LRU cache: exposes classes
- Rust extension API → Random replacement: exposes classes
- Rust extension API → TTL cache: exposes classes
- Rust extension API → Variable TTL cache: exposes classes
- Generic cache → Base cache type: uses base type (evidence: `src/pyclasses/cache.rs`)
- FIFO cache → Base cache type: uses base type (evidence: `src/pyclasses/fifocache.rs`)
- LFU cache → Base cache type: uses base type (evidence: `src/pyclasses/lfucache.rs`)
- LRU cache → Base cache type: uses base type (evidence: `src/pyclasses/lrucache.rs`)
- Random replacement → Base cache type: uses base type (evidence: `src/pyclasses/rrcache.rs`)
- TTL cache → Base cache type: uses base type (evidence: `src/pyclasses/ttlcache.rs`)
- Variable TTL cache → Base cache type: uses base type (evidence: `src/pyclasses/vttlcache.rs`)
- Generic cache → Common operations: uses operations (evidence: `src/pyclasses/cache.rs`)
- FIFO cache → FIFO policy: uses policy (evidence: `src/pyclasses/fifocache.rs`)
- LFU cache → LFU policy: uses policy (evidence: `src/pyclasses/lfucache.rs`)
- LRU cache → LRU policy: uses policy (evidence: `src/pyclasses/lrucache.rs`)
- Random replacement → Other policies: uses policy (evidence: `src/pyclasses/rrcache.rs`)
- TTL cache → TTL policy: uses policy (evidence: `src/pyclasses/ttlcache.rs`)
- Variable TTL cache → Variable TTL policy: uses policy (evidence: `src/pyclasses/vttlcache.rs`)
- FIFO policy → Policy interfaces: implements (evidence: `src/policies/fifopolicy.rs`)
- LFU policy → Policy interfaces: implements (evidence: `src/policies/lfupolicy.rs`)
- LRU policy → Policy interfaces: implements (evidence: `src/policies/lrupolicy.rs`)
- TTL policy → Policy interfaces: implements (evidence: `src/policies/ttlpolicy.rs`)
- Variable TTL policy → Policy interfaces: implements (evidence: `src/policies/vttlpolicy.rs`)
- FIFO policy → Shared policy logic: uses helpers (evidence: `src/policies/fifopolicy.rs`)
- LFU policy → Shared policy logic: uses helpers (evidence: `src/policies/lfupolicy.rs`)
- LRU policy → Shared policy logic: uses helpers (evidence: `src/policies/lrupolicy.rs`)
- TTL policy → Shared policy logic: uses helpers (evidence: `src/policies/ttlpolicy.rs`)
- Variable TTL policy → Shared policy logic: uses helpers (evidence: `src/policies/vttlpolicy.rs`)
- Common operations → Policy interfaces: wraps policies (evidence: `src/policies/wrapped.rs`)
- LFU policy → Lazy heap: uses heap (evidence: `src/policies/lfupolicy.rs`)
- Variable TTL policy → Lazy heap: uses heap (evidence: `src/policies/vttlpolicy.rs`)
- LRU policy → Linked list: uses list (evidence: `src/policies/lrupolicy.rs`)
- FIFO policy → SwissTable storage: uses table (evidence: `src/policies/fifopolicy.rs`)
- LFU policy → SwissTable storage: uses table (evidence: `src/policies/lfupolicy.rs`)
- LRU policy → SwissTable storage: uses table (evidence: `src/policies/lrupolicy.rs`)
- TTL policy → SwissTable storage: uses table (evidence: `src/policies/ttlpolicy.rs`)
- Variable TTL policy → SwissTable storage: uses table (evidence: `src/policies/vttlpolicy.rs`)
- Generic cache → Thread-safe init: initializes through (evidence: `src/pyclasses/cache.rs`)
- LFU cache → Thread-safe init: initializes through (evidence: `src/pyclasses/lfucache.rs`)
- TTL cache → Thread-safe init: initializes through (evidence: `src/pyclasses/ttlcache.rs`)
