# mgtv-tech/jetcache-go architecture

> Architecture diagram of the GitHub repository mgtv-tech/jetcache-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mgtv-tech/jetcache-go
- Repository: https://github.com/mgtv-tech/jetcache-go

## Overview

##### Project Type and Purpose
- This is a library/framework—not an end-user application—that enables developers to integrate flexible caching (both local memory caching and remote caching via Redis) into their Go projects.
- The framework implements features inspired by JetCache for Java, offering pluggable modules (local cache, remote cache, encoding, logging, stats collection, etc.) and supports extension with custom implementations.

##### And Represent Main Components
- Core Cache Module: Represent the central “cache” component (as indicated by core files like cache.go and item.go). This module handles cache operations (Get, Set, Once, MGet, etc.) and overall orchestration.
- Local Cache Module: Include a component representing the “local” directory’s implementations (FreeCache, TinyLFU, etc.). This component serves as the in-memory caching layer.
- Logger: Include the “logger” module, which handles default logging and might be used for debugging or tracking metrics.
- Statistics and Metrics: Represent the “stats” module that collects and logs statistical information (hit rates, QPM, etc.).

##### Data Flow and Interactions
- Inside the core, split the interaction into local and remote caching:
- A feedback path for asynchronous operations such as refreshing remote caches and local cache invalidation which may involve an event handler (as indicated in the syncLocal mechanism using pub/sub). This path might also interact with the Logger so that events and errors are published.
- Optionally, show interactions with external systems (e.g., the Go-Redis client communicating with an external Redis cluster).

##### Architectural Patterns and Design Principles
- That the library uses the “singleflight” (Once interface) pattern to prevent duplicate calls during cache misses.
- Pluggability and configuration, as users can customize caching strategies such as error handling (custom errNotFound), encoding strategies (MsgPack/sonic/JSON), and remote expiry.
- Separation of concerns by showing distinct layers (API/Core, local caching, remote caching, encoding, logging, and metrics).

##### Inclusion of Relevant Technologies
- That the remote caching leverages Go-Redis (v9).
- Availability of different encoding libraries such as MsgPack (default) and sonic.
- Optionally, highlight other frameworks used such as FreeCache and TinyLFU for local caching.

- That every component (Core Cache, Local Cache, Remote Cache, Encoding, Logger, Stats, Utils) is clearly labeled.
- Data flow from the client to the core logic.
- API calls to local vs. remote modules.
- Asynchronous events (like pub/sub for local cache invalidation).
- Internal modules (core, encoding, utils) versus external dependencies (Redis).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Integration
    subgraph "User Integration"
        client["Client (User Code)"]:::api
    end

    %% Caching Framework Components
    subgraph "Caching Framework"
        cc["Core Cache Module"]:::internal
        lc["Local Cache Module"]:::internal
        rc["Remote Cache Module"]:::internal
        enc["Encoding/Decoding Module"]:::internal
        log["Logger"]:::internal
        st["Statistics & Metrics"]:::internal
        ut["Utilities"]:::internal
    end

    %% External Systems
    subgraph "External Systems"
        redis["Redis Cluster"]:::external
    end

    %% Connections between components
    client -->|"calls"| cc
    cc -->|"local_retrieval"| lc
    cc -->|"remote_call"| rc
    cc -->|"data_encoding"| enc
    rc -->|"pubsub_invalidation"| lc
    rc -->|"communicates_with"| redis
    cc -->|"logs_events"| log
    log -->|"updates_stats"| st

    %% Click Events for Project File Mapping
    click cc "https://github.com/mgtv-tech/jetcache-go/blob/main/cache.go"
    click cc "https://github.com/mgtv-tech/jetcache-go/blob/main/item.go"
    click cc "https://github.com/mgtv-tech/jetcache-go/blob/main/cachegeneric.go"
    click cc "https://github.com/mgtv-tech/jetcache-go/blob/main/cacheopt.go"
    click lc "https://github.com/mgtv-tech/jetcache-go/tree/main/local/"
    click rc "https://github.com/mgtv-tech/jetcache-go/tree/main/remote/"
    click enc "https://github.com/mgtv-tech/jetcache-go/tree/main/encoding/"
    click log "https://github.com/mgtv-tech/jetcache-go/tree/main/logger/"
    click st "https://github.com/mgtv-tech/jetcache-go/tree/main/stats/"
    click ut "https://github.com/mgtv-tech/jetcache-go/tree/main/util/"

    %% Styles for nodes
    classDef internal fill:#ffefc6,stroke:#d2a679,stroke-width:2px,color:#000;
    classDef external fill:#c6e2ff,stroke:#5a8dd8,stroke-width:2px,color:#000;
    classDef api fill:#d1f5d3,stroke:#5cb85c,stroke-width:2px,color:#000;
```
