# sai007nikhil/smart-cache architecture

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

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

## Overview

##### Project Type and Purpose
- SmartCache is a standalone caching service (a backend microservice) written in Go.
- Purpose: Provide high‐performance in-memory caching with TTL, hybrid eviction (LRU+LFU), optional disk persistence, and a RESTful API.

##### File Structure
- Top‐level modules:
- api/        → HTTP endpoint handlers
- cache/      → Core in-memory key-value store
- eviction/   → Eviction strategies (LRU, LFU, Hybrid)
- persistence/→ Disk persistence backends (BoltDB, BadgerDB, WAL)
- config/     → Configuration loader (YAML/JSON/env)
- k8s/, Dockerfile, docker-compose.yml → Deployment artifacts
- main.go ties everything together: loads config, initializes modules, starts HTTP server.
- Test files and scripts demonstrate high concurrency, benchmarks, and integration tests.

##### Extract Architectural Insights from the README
- Modular architecture: Cache Core, Eviction Engine, Persistence Layer, API Layer, Configuration.
- Key design goals: thread safety (fine-grained locking), pluggable eviction, optional persistence, TTL GC.
- Production readiness: Docker, K8s, configurable via YAML or env vars.

##### Main Components and Their Relationships
a. API Layer
- Exposes REST endpoints (/api/v1/cache, /stats)
- Forwards requests to Cache Core
b. Cache Core
- In-memory key-value store
- Handles TTL expiration by background GC
- Delegates eviction decisions to Eviction Engine
- Invokes Persistence Layer for writes/reads if enabled
c. Eviction Engine (pluggable)
- Implements LRU, LFU, or Hybrid strategies
- Configurable weights (hybrid_alpha, hybrid_beta)
- API: `Evictor.Evict()`
d. Persistence Layer (optional)
- Two backends: BoltDB or BadgerDB
- Uses WAL (Write-Ahead Logging) for durability
- Snapshotting at intervals
e. Configuration Manager
- Reads YAML/JSON or environment variables
- Supplies parameters to all modules: server mode/port, cache size, TTL, eviction policy, persistence options
f. Infrastructure Modules
- Dockerfile & docker-compose.yml for containerization
- k8s/ for Kubernetes deployment, service, PVC, configmap

##### Architectural Patterns and Principles
- Modular monolith: clear separation of concerns (API vs. business logic vs. persistence)
- Strategy pattern: eviction methods pluggable at runtime
- Dependency injection: modules wired together in main.go based on config
- Concurrency control: fine-grained locks within Cache Core, safe for 100K+ ops/sec
- Observer/ticker for TTL GC

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["External Clients<br/>(curl, scripts)"]:::external

    %% Main Entry Point and Config
    Main["main.go (Entry Point)"]:::core
    Config["Config Manager"]:::config
    DefaultConfig["config.yaml"]:::config

    %% API Layer
    subgraph "API Layer"
        API["API Server (HTTP)"]:::api
    end

    %% In-Memory Layer
    subgraph "In-Memory Layer"
        Core["Cache Core"]:::core
        Entry["Cache Entry Definitions"]:::core
    end

    %% Eviction Engine
    subgraph "Eviction Engine"
        Evictor["Evictor Interface & Factory"]:::core
        LRU["LRU Strategy"]:::core
        LFU["LFU Strategy"]:::core
        Hybrid["Hybrid Strategy"]:::core
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        PersistInterface["Persistence Layer Interface"]:::storage
        Bolt["BoltDB Backend"]:::storage
        Badger["BadgerDB Backend"]:::storage
        WAL["Write-Ahead Log (WAL)"]:::storage
    end

    %% Background GC
    GC["Background TTL GC"]:::core

    %% Infrastructure
    subgraph "Infrastructure"
        Dockerfile["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
        K8sDep["k8s/deployment.yaml"]:::infra
        K8sSvc["k8s/service.yaml"]:::infra
        K8sCfg["k8s/configmap.yaml"]:::infra
        K8sPVC["k8s/pvc.yaml"]:::infra
    end

    %% Connections
    Clients -->|"GET/POST →"| API
    API -->|"Forward Request →"| Core
    Core -->|"Evict() →"| Evictor
    Evictor -->|"Use →"| LRU
    Evictor -->|"Use →"| LFU
    Evictor -->|"Use →"| Hybrid
    Core -->|"Persist() →"| PersistInterface
    PersistInterface -->|"Use →"| Bolt
    PersistInterface -->|"Use →"| Badger
    PersistInterface -->|"Use →"| WAL
    Core -->|"Starts →"| GC
    GC -->|"Collects TTL →"| Core

    %% Initialization and Config Injection
    Main -->|"Load Config & DI →"| Config
    Main -->|"Init →"| API
    Main -->|"Init →"| Core
    Main -->|"Init →"| Evictor
    Main -->|"Init →"| PersistInterface
    Main -->|"Init →"| GC
    Config -.-> API
    Config -.-> Core
    Config -.-> Evictor
    Config -.-> PersistInterface
    Config -.-> GC
    Config -.-> Main
    DefaultConfig -.-> Config

    %% Click Events
    click API "https://github.com/sai007nikhil/smart-cache/blob/main/api/http.go"
    click Core "https://github.com/sai007nikhil/smart-cache/blob/main/cache/cache.go"
    click Entry "https://github.com/sai007nikhil/smart-cache/blob/main/cache/entry.go"
    click Evictor "https://github.com/sai007nikhil/smart-cache/blob/main/eviction/evictor.go"
    click LRU "https://github.com/sai007nikhil/smart-cache/blob/main/eviction/lru.go"
    click LFU "https://github.com/sai007nikhil/smart-cache/blob/main/eviction/lfu.go"
    click Hybrid "https://github.com/sai007nikhil/smart-cache/blob/main/eviction/hybrid.go"
    click PersistInterface "https://github.com/sai007nikhil/smart-cache/blob/main/persistence/interface.go"
    click Bolt "https://github.com/sai007nikhil/smart-cache/blob/main/persistence/bolt.go"
    click Badger "https://github.com/sai007nikhil/smart-cache/blob/main/persistence/badger.go"
    click WAL "https://github.com/sai007nikhil/smart-cache/blob/main/persistence/wal.go"
    click Config "https://github.com/sai007nikhil/smart-cache/blob/main/config/config.go"
    click DefaultConfig "https://github.com/sai007nikhil/smart-cache/blob/main/config.yaml"
    click Main "https://github.com/sai007nikhil/smart-cache/blob/main/main.go"
    click Dockerfile "https://github.com/sai007nikhil/smart-cache/tree/main/Dockerfile"
    click Compose "https://github.com/sai007nikhil/smart-cache/blob/main/docker-compose.yml"
    click K8sDep "https://github.com/sai007nikhil/smart-cache/blob/main/k8s/deployment.yaml"
    click K8sSvc "https://github.com/sai007nikhil/smart-cache/blob/main/k8s/service.yaml"
    click K8sCfg "https://github.com/sai007nikhil/smart-cache/blob/main/k8s/configmap.yaml"
    click K8sPVC "https://github.com/sai007nikhil/smart-cache/blob/main/k8s/pvc.yaml"

    %% Styles
    classDef api fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef core fill:#87CEFA,stroke:#333,stroke-width:1px;
    classDef storage fill:#98FB98,stroke:#333,stroke-width:1px;
    classDef config fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef external fill:#F5DEB3,stroke:#333,stroke-width:1px;
```
