# foyer-rs/foyer architecture

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

- Interactive diagram: https://gitdiagram.com/foyer-rs/foyer
- Repository: https://github.com/foyer-rs/foyer

## Overview

##### Main Components
- Library Core (foyer): This is the central crate where the primary API is exposed. It integrates the various functionalities of hybrid caching.
- In-Memory Cache (foyer-memory): Responsible for managing the in-memory cache, including different eviction strategies (LRU, FIFO, LFU, etc.). It implements zero-copy cache abstractions and provides high-performance thread-safe access.
- Disk Storage Engine (foyer-storage): Handles persistent storage for caching, managing both “large” and “small” objects, compression support, and device I/O. It includes specialized modules (such as device management, indexer, compressor, and statistics).
- Common Utilities (foyer-common): Contains shared modules (e.g., for metrics, tracing, asynchronous utilities, and testing helpers) that are used by both memory and storage components.
- CLI and Benchmarking Tools (foyer-cli and foyer-bench): These crates provide command-line interfaces and benchmarking utilities to aid both users and developers.
- Examples and Scripts: Located under the “examples” and “scripts” directories, they demonstrate different configurations and integrations (like Prometheus, Grafana, and tail-based tracing integrations).

##### Relationships and Interactions
- At the top level, application code (or external users) calls the API provided by the main “foyer” crate.
- The main API delegates caching operations to either the in-memory cache component (from foyer-memory) or, in a hybrid setup, to the storage engine (from foyer-storage) based on configuration.
- The common utilities in foyer-common support both memory and storage by offering shared infrastructure (for example, for event tracing, metrics, and utilities for asynchronous operations).
- The CLI tool (foyer-cli) interacts with the core to provide a user-friendly entry point, and the benchmark suite (foyer-bench) is used for performance testing.
- External integrations, as showcased in examples and configuration files under “etc”, show how observability (Prometheus, Grafana) gets integrated into the system.

##### Architectural Patterns and Principles
- Modular Design: Each major function (in-memory caching, storage engine, utilities) is separated into its own crate. This separation promotes clean boundaries and easier maintenance.
- Hybrid Cache Architecture: The central concept of combining an in-memory cache with a secondary disk cache is the core design principle. The project separates policies and algorithms for eviction, admission, and recovery.
- Configurability & Extensibility: The project exposes plug-and-play caching algorithms and configurations (e.g., different eviction strategies, compression options, and runtime options) that allow customization for diverse workloads.
- Concurrency & Performance: With a focus on high concurrency and low latency (using thread-safe mechanisms and asynchronous runtimes), the design supports heavy workloads.

##### Detailed Focus Areas
- Separation of Concerns: Make it obvious that the in-memory caching logic and disk storage logic are decoupled components that communicate through the hybrid cache API.
- Data Flow: Represent how a cache “get” or “insert” operation flows from the user’s call through the API, then into the memory cache, and potentially falls back to the disk storage if not found.
- Extensibility: Indicate configurable hooks like customizable eviction policies, compression options (e.g., Lz4), and runtime options.
- External Observability: Show how the project integrates with external systems (e.g., Prometheus metrics paths, Grafana dashboards) provided in the “etc” directory.
- Tooling: Highlight supporting tools (CLI and Bench) that assist in monitoring, testing, and benchmarking the different subsystems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interaction"
        User["User/Application"]:::external
        Examples["Examples and Scripts"]:::examples
    end

    subgraph "Core System"
        FoyerCore["Foyer Core (API)"]:::core
        MemoryCache["In-Memory Cache (LRU/FIFO)"]:::cache
        DiskStorage(("Disk Storage Engine")):::storage
        SharedUtil["Shared Utilities (foyer-common)"]:::utilities
    end

    subgraph "Tooling"
        CLITools["CLI Tools"]:::tools
        BenchTools["Benchmarking Tools"]:::tools
    end

    subgraph "External Integrations"
        Prometheus["Prometheus"]:::externalIntegration
        Grafana["Grafana"]:::externalIntegration
    end

    User -->|"calls"| FoyerCore
    Examples -->|"demonstrates"| FoyerCore

    FoyerCore -->|"delegates"| MemoryCache
    FoyerCore -->|"delegates"| DiskStorage
    FoyerCore -->|"triggers"| CLITools
    FoyerCore -->|"triggers"| BenchTools

    FoyerCore <-->|"uses"| SharedUtil
    MemoryCache <-->|"supports"| SharedUtil
    DiskStorage <-->|"supports"| SharedUtil

    SharedUtil -->|"reports"| Prometheus
    SharedUtil -->|"reports"| Grafana

    classDef core fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef cache fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef storage fill:#ffcc80,stroke:#333,stroke-width:2px;
    classDef utilities fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef tools fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef externalIntegration fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef external fill:#e8daef,stroke:#333,stroke-width:2px;
    classDef examples fill:#fef9e7,stroke:#333,stroke-width:2px;

    click FoyerCore "https://github.com/foyer-rs/foyer/blob/main/foyer/src/lib.rs"
    click MemoryCache "https://github.com/foyer-rs/foyer/blob/main/foyer-memory/src/cache.rs"
    click DiskStorage "https://github.com/foyer-rs/foyer/blob/main/foyer-storage/src/engine.rs"
    click SharedUtil "https://github.com/foyer-rs/foyer/blob/main/foyer-common/src/lib.rs"
    click CLITools "https://github.com/foyer-rs/foyer/blob/main/foyer-cli/src/main.rs"
    click BenchTools "https://github.com/foyer-rs/foyer/blob/main/foyer-bench/src/main.rs"
    click Examples "https://github.com/foyer-rs/foyer/tree/main/examples/"
    click Prometheus "https://github.com/foyer-rs/foyer/tree/main/etc/prometheus"
    click Grafana "https://github.com/foyer-rs/foyer/tree/main/etc/grafana"
```
