# ponder2000/cache architecture

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

- Interactive diagram: https://gitdiagram.com/ponder2000/cache
- Repository: https://github.com/ponder2000/cache

## Overview

This is an in-memory Go cache library with key-value and FIFO-list caches, per-item expiration, and pooled janitors that periodically purge registered caches. The principal workflow is: a caller creates a cache and janitor pool, registers caches, then the janitors invoke each cache’s purge operation on a ticker. The graph also shows the public facade, cache interface and shared item-expiration model. Edges are limited to relationships visible in the excerpts or README; unsampled behavior is omitted.

Main entry points: [`cache.go`](https://github.com/ponder2000/cache/blob/main/cache.go) (Cache Facade), [`pkg/container/cacher.go`](https://github.com/ponder2000/cache/blob/main/pkg/container/cacher.go) (Cache Interfaces), [`pkg/janitor/pool.go`](https://github.com/ponder2000/cache/blob/main/pkg/janitor/pool.go) (Janitor Pool), [`pkg/container/keyvalue/cache.go`](https://github.com/ponder2000/cache/blob/main/pkg/container/keyvalue/cache.go) (Key-Value Cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_facade["Cache Facade<br/>[cache.go]"]
  node_cache_interface["Cache Interfaces<br/>[cacher.go]"]
end

subgraph group_stores["Cache Stores"]
  node_map_cache["Key-Value Cache<br/>[cache.go]"]
  node_list_cache["FIFO List Cache<br/>[cache.go]"]
end

subgraph group_expiry["Expiration Core"]
  node_item["Expiring Item<br/>[item.go]"]
end

subgraph group_cleanup["Janitor Cleanup"]
  node_janitor_config["Janitor Config<br/>[config.go]"]
  node_janitor_pool["Janitor Pool<br/>[pool.go]"]
  node_janitor["Janitor Worker<br/>[janitor.go]"]
end

node_caller(("Library Caller"))

node_caller -->|"uses"| node_facade
node_facade -->|"creates config"| node_janitor_config
node_facade -->|"creates pool"| node_janitor_pool
node_facade -->|"creates caches"| node_cache_interface
node_facade -->|"creates map cache"| node_map_cache
node_facade -->|"creates list cache"| node_list_cache
node_cache_interface -->|"constructs"| node_map_cache
node_cache_interface -->|"constructs"| node_list_cache
node_janitor_pool -->|"creates and starts"| node_janitor
node_janitor_pool -->|"uses options"| node_janitor_config
node_janitor -->|"purges caches"| node_cache_interface
node_map_cache -->|"creates and checks"| node_item
node_list_cache -->|"creates and checks"| node_item

click node_facade "https://github.com/ponder2000/cache/blob/main/cache.go"
click node_cache_interface "https://github.com/ponder2000/cache/blob/main/pkg/container/cacher.go"
click node_janitor_config "https://github.com/ponder2000/cache/blob/main/pkg/janitor/config.go"
click node_janitor_pool "https://github.com/ponder2000/cache/blob/main/pkg/janitor/pool.go"
click node_janitor "https://github.com/ponder2000/cache/blob/main/pkg/janitor/janitor.go"
click node_map_cache "https://github.com/ponder2000/cache/blob/main/pkg/container/keyvalue/cache.go"
click node_list_cache "https://github.com/ponder2000/cache/blob/main/pkg/container/list/cache.go"
click node_item "https://github.com/ponder2000/cache/blob/main/pkg/core/item.go"

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_cache_interface toneBlue
class node_map_cache,node_list_cache toneAmber
class node_item toneMint
class node_janitor_config,node_janitor_pool,node_janitor toneRose
class node_caller toneIndigo
```

## Components

### Public API

- [Cache Facade](https://github.com/ponder2000/cache/blob/main/cache.go): `cache.go`
- [Cache Interfaces](https://github.com/ponder2000/cache/blob/main/pkg/container/cacher.go): `pkg/container/cacher.go`

### Cache Stores

- [Key-Value Cache](https://github.com/ponder2000/cache/blob/main/pkg/container/keyvalue/cache.go): `pkg/container/keyvalue/cache.go`
- [FIFO List Cache](https://github.com/ponder2000/cache/blob/main/pkg/container/list/cache.go): `pkg/container/list/cache.go`

### Expiration Core

- [Expiring Item](https://github.com/ponder2000/cache/blob/main/pkg/core/item.go): `pkg/core/item.go`

### Janitor Cleanup

- [Janitor Config](https://github.com/ponder2000/cache/blob/main/pkg/janitor/config.go): `pkg/janitor/config.go`
- [Janitor Pool](https://github.com/ponder2000/cache/blob/main/pkg/janitor/pool.go): `pkg/janitor/pool.go`
- [Janitor Worker](https://github.com/ponder2000/cache/blob/main/pkg/janitor/janitor.go): `pkg/janitor/janitor.go`

### Other components

- **Library Caller**

## Connections

- Library Caller → Cache Facade: uses (evidence: `README.md`)
- Cache Facade → Janitor Config: creates config (evidence: `cache.go`)
- Cache Facade → Janitor Pool: creates pool (evidence: `cache.go`)
- Cache Facade → Cache Interfaces: creates caches (evidence: `cache.go`)
- Cache Facade → Key-Value Cache: creates map cache (evidence: `cache.go`)
- Cache Facade → FIFO List Cache: creates list cache (evidence: `cache.go`)
- Cache Interfaces → Key-Value Cache: constructs (evidence: `pkg/container/cacher.go`)
- Cache Interfaces → FIFO List Cache: constructs (evidence: `pkg/container/cacher.go`)
- Janitor Pool → Janitor Worker: creates and starts (evidence: `pkg/janitor/pool.go`)
- Janitor Pool → Janitor Config: uses options (evidence: `pkg/janitor/pool.go`)
- Janitor Worker → Cache Interfaces: purges caches (evidence: `pkg/janitor/janitor.go`)
- Key-Value Cache → Expiring Item: creates and checks (evidence: `pkg/container/keyvalue/cache.go`)
- FIFO List Cache → Expiring Item: creates and checks (evidence: `pkg/container/list/cache.go`)