# allegro/bigcache architecture

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

- Interactive diagram: https://gitdiagram.com/allegro/bigcache
- Repository: https://github.com/allegro/bigcache

## Overview

##### Project Type and Purpose
- BigCache is a high-performance, in-memory cache library for Go (requires Go 1.12+).
- It provides lock-sharded storage of entries in large byte slices to avoid GC pressure.
- It also offers an HTTP wrapper (in the `server` package) exposing cache operations over REST.

##### File Structure
- Top-level Go files (e.g., `bigcache.go`, `config.go`, `shard.go`) implement the core caching logic.
- Utility files (`hash.go`, `encoding.go`, `iterator.go`, `stats.go`, `utils.go`) support hashing, serialization, iteration, metrics, etc.
- `queue/` implements the eviction queue used by each shard.
- `server/` contains an HTTP server (`server.go`) with handlers (`cache_handlers.go`, `stats_handler.go`), plus middleware.
- Tests (`*_test.go`) and benchmarks live alongside production code.

##### Key Components
A. Configuration Module
- `Config` struct: shard count, life/clean windows, max-entry size, callbacks.
B. Cache Manager (`BigCache` struct in `bigcache.go`)
- Holds a slice of Shard instances.
- Exposes methods: `Set`, `Get`, `Delete`, `Len`, `Reset`, `Iterator`.
- Spins up background cleanup (ticker) per config.
C. Shard
- Contains:
- `map[uint64]uint32` for hash→offset lookup
- large byte slices storing concatenated entries
- an eviction `queue` of entry timestamps/offsets
- `sync.RWMutex` to guard concurrent access
- Handles entry insertion, lookup, expiry marking.
D. Hashing Subsystem
- `fnv.go`: FNV-1a hash of keys → `uint64` shard index and map key.
E. Eviction & Cleanup
- `queue/bytes_queue.go`: ring buffer / time-ordered slots
- Periodic clean job (driven by `CleanWindow`) that pops expired offsets and frees space.
F. Stats & Logging
- `stats.go`: collects metrics per shard (hits, misses, entries).
- `logger.go`: optional verbose output for allocations.
G. Iterator
- `iterator.go`: sequential scan over shards/entries for range operations.
H. HTTP Server (optional)
- `server/server.go`: HTTP router
- Handlers: GET/SET/DELETE for entries, GET for stats
- `middleware.go`: logging, request parsing

##### Component Relationships and Data Flow
- Client code calls `bigcache.New(config)` → instantiates Cache Manager → allocates shards with queues & byte buffers.
- `Set(key, value)`:
1. Hash key → determine shard
2. Lock shard, append entry bytes to slice, update map, push timestamp into queue
3. Release lock
- `Get(key)`:
1. Hash key → shard
2. RLock shard, lookup offset, read bytes, return value
3. Release lock
- Cleanup goroutine (per BigCache instance): wakes every `CleanWindow`, iterates shards, evicts expired offsets via their queues.
- If HTTP server is enabled:
- External HTTP client → router → appropriate handler → calls underlying `Set`/`Get` → returns HTTP response

##### Architectural Patterns and Principles
- Shard-based partitioning to maximize parallelism (lock striping).
- Zero-GC design: contiguous byte buffers + primitive map types avoid GC pressure.
- Separation of concerns: hashing, storage management, eviction, stats, and presentation (HTTP) are modularized.
- Configurable eviction callbacks for extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% API Layer
    subgraph "API Layer"
        direction TB
        API["API: Set/Get/Delete"]:::core
        Iterator["Iterator"]:::core
    end

    %% Core Cache Library
    subgraph "Core Cache Library"
        direction TB
        Config["Config"]:::core
        BigCache["BigCache (Cache Manager)"]:::core
        Hashing["Hashing Subsystem"]:::core
        subgraph "Shard Pool"
            direction TB
            Shard["Shard"]:::core
            MapIndex["Map Index"]:::core
            ByteStore["Byte Slice Store"]:::core
            EvictQueue["Eviction Queue"]:::queue
            Mutex["Mutex"]:::core
        end
        Cleanup["Cleanup Ticker"]:::core
        Stats["Stats Collection"]:::stats
        Logger["Logger"]:::stats
    end

    %% HTTP Server Optional Layer
    subgraph "HTTP Server (Optional)"
        direction TB
        HTTPServer["HTTP Server"]:::http
        Middleware["Middleware"]:::http
        CacheH["Cache Handlers"]:::http
        StatsH["Stats Handler"]:::http
    end

    %% Connections
    API --> BigCache
    Iterator --> BigCache
    BigCache --> Hashing
    BigCache --> Shard
    Hashing --> Shard
    Shard --> MapIndex
    Shard --> ByteStore
    Shard --> EvictQueue
    Shard --> Mutex
    Cleanup --> Shard
    Cleanup --> EvictQueue
    BigCache --> Cleanup
    BigCache --> Stats
    BigCache --> Logger
    HTTPServer --> Middleware
    Middleware --> CacheH
    Middleware --> StatsH
    CacheH --> BigCache
    StatsH --> Stats

    %% Click Events
    click Config "https://github.com/allegro/bigcache/blob/main/config.go"
    click BigCache "https://github.com/allegro/bigcache/blob/main/bigcache.go"
    click Shard "https://github.com/allegro/bigcache/blob/main/shard.go"
    click Hashing "https://github.com/allegro/bigcache/blob/main/fnv.go"
    click EvictQueue "https://github.com/allegro/bigcache/blob/main/queue/bytes_queue.go"
    click Stats "https://github.com/allegro/bigcache/blob/main/stats.go"
    click Logger "https://github.com/allegro/bigcache/blob/main/logger.go"
    click Iterator "https://github.com/allegro/bigcache/blob/main/iterator.go"
    click HTTPServer "https://github.com/allegro/bigcache/blob/main/server/server.go"
    click CacheH "https://github.com/allegro/bigcache/blob/main/server/cache_handlers.go"
    click StatsH "https://github.com/allegro/bigcache/blob/main/server/stats_handler.go"
    click Middleware "https://github.com/allegro/bigcache/blob/main/server/middleware.go"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000
    classDef queue fill:#FFA500,stroke:#000
    classDef stats fill:#90EE90,stroke:#000
    classDef http fill:#D8BFD8,stroke:#000
```
