# abiiranathan/gokache architecture

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

- Interactive diagram: https://gitdiagram.com/abiiranathan/gokache
- Repository: https://github.com/abiiranathan/gokache

## Overview

##### Project Type and Purpose
- Type: Go library (importable module), not a full service.
- Purpose: Provide a highly concurrent in-memory cache with:
– Sharding (256 internal shards)
– TTL on items
– Background cleanup of expired entries
– Persistence (save/load via gob)
– Graceful shutdown

##### Main Components
a. Client / Application Code
– Calls Cache API (NewCache, Set, Get, Delete, SaveToDisk, LoadFromDisk, Close)
b. Cache Manager
– The `Cache` struct that holds configuration, shard array, cleanup ticker, and persistence hooks.
c. Shard Array
– 256 independent shards
– Each shard = a Go map[key]item + `sync.RWMutex`
– Key hashing → determines target shard
d. In-Memory Item Store
– Each stored value wrapped with metadata: insertion timestamp + TTL
e. Background Cleanup Goroutine
– Ticker based on `cleanupInterval`
– Iterates shards → locks each shard → purges expired items
f. Persistence Layer
– SaveToDisk: locks all shards → marshals full state via `encoding/gob` → writes to filesystem
– LoadFromDisk: reads file → decodes gob → repopulates shards
g. Shutdown Handler
– `Close()` stops cleanup ticker/goroutine and optionally triggers final cleanup

##### Relationships and Data Flows
- API calls (Set, Get, Delete) → go through Cache Manager → compute shard index → shard lock → read/write map
- Background cleanup ticker → triggers shard sweeps in separate goroutine
- Save/Load operations ↔ filesystem (snapshot file on disk)
- Close() → signals cleanup goroutine to exit + final resource cleanup

##### Architectural Patterns & Principles
– Sharding for horizontal concurrency (minimizes lock contention)
– Single‐responsibility components: Cache Manager vs. Shards vs. Persistence
– Graceful shutdown & safe concurrency using channels/tickers and sync primitives
– Library pattern: exposes a clean, minimal API surface to host applications

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Side"
        Client["Client/Application Code"]:::control
    end
    Client -->|"NewCache()/Set/Get/Delete/Close"| Manager

    subgraph "gokache Library"
        Manager["Cache Manager"]:::inMemory
        Manager -->|"hash(key)"| Shard["Shard[0..255]"]:::inMemory

        subgraph "Shard Internals"
            ShardMap["map[string]Item"]:::inMemory
            Lock["sync.RWMutex"]:::control
            Item["Item(value, expiresAt)"]:::inMemory
            ShardMap --> Item
            Lock --- ShardMap
        end

        Manager -->|"cleanupTicker"| Cleanup["Background Cleanup Goroutine"]:::control
        Cleanup -->|"sweep expired items"| Shard

        Manager -->|"SaveToDisk()/LoadFromDisk()"| Persistence["Persistence Layer"]:::persistence
    end

    Persistence -->|"marshal/unmarshal via gob"| Disk["Disk File"]:::persistence

    Test1["General Cache Tests"]:::control
    Test2["Persistence Tests"]:::control
    Test1 -.-> Manager
    Test2 -.-> Persistence

    click Client "https://github.com/abiiranathan/gokache/blob/main/README.md"
    click Manager "https://github.com/abiiranathan/gokache/blob/main/cache.go"
    click Shard "https://github.com/abiiranathan/gokache/blob/main/cache.go"
    click ShardMap "https://github.com/abiiranathan/gokache/blob/main/cache.go"
    click Lock "https://github.com/abiiranathan/gokache/blob/main/cache.go"
    click Item "https://github.com/abiiranathan/gokache/blob/main/cache.go"
    click Cleanup "https://github.com/abiiranathan/gokache/blob/main/cache.go"
    click Persistence "https://github.com/abiiranathan/gokache/blob/main/cache.go"
    click Test1 "https://github.com/abiiranathan/gokache/blob/main/cache_test.go"
    click Test2 "https://github.com/abiiranathan/gokache/blob/main/persistance_test.go"

    classDef inMemory fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef control fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef persistence fill:#fff3cd,stroke:#333,stroke-width:1px;
```
