# ben-manes/caffeine architecture

> Architecture diagram of the GitHub repository ben-manes/caffeine, 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/ben-manes/caffeine
- Repository: https://github.com/ben-manes/caffeine

## Overview

##### Main Components
- Core Caching Library (“caffeine” module): This is the heart of the project. It contains the primary cache implementation, including functions like eviction, time‐based expiration, refresh, and statistics. Look at the files under caffeine/src/main/java (and its subpackages) for insight into its internal structure.
- Adapters/Extensions: Modules such as “guava” and “jcache” adapt the core API to other flavors/standards. They wrap or integrate the core library to provide compatibility with other systems.
- Simulator: The “simulator” module houses tools for evaluating cache strategies (eviction policies, admission control, etc.). This is a specialized component that likely leverages the same core components in a test/simulation environment.
- Example Projects: Under the “examples” directory (with subprojects like “graal-native”, “hibernate”, “indexable”, “resilience-failsafe”, and “write-behind-rxjava”), you have various sample implementations. These are intended to demonstrate how the caching library can be used in real-world scenarios or with external frameworks.
- Build, Integration, and Quality Infrastructure: The presence of multiple Gradle build scripts (build.gradle.kts, gradle plugins, etc.), CI/CD configuration (.github/workflows, .circleci), and code quality configuration indicates that the project architecture also includes robust build, test, and deployment pipelines.

##### Relationships and Interactions
- The Core Caching Library is central, with the adapters and examples depending directly upon it. The core provides the caching functionality and eviction policies that are then “wrapped” by modules like “guava” and “jcache.”
- The Simulator module interacts with the core cache to test different eviction policies and cache behaviors under varying workloads.
- The Example projects serve as usage scenarios that demonstrate integration with other frameworks (e.g., Hibernate, GraalVM, Spring, etc.). They essentially show external clients wiring into the core caching library.
- The build scripts and CI/CD configurations integrate all modules for continuous integration, code analysis, testing, and deployment to Maven Central.

##### Architectural Patterns and Design Principles
- Modularity: Each major functionality (core caching, adapters, simulation, and examples) is split into separate modules. This promotes reuse and easier maintenance.
- Layered Architecture: The core caching library represents the business logic layer, while the adapters provide abstraction layers to interface with third-party systems. The simulation and testing layers help validate performance and correctness.
- API-Driven: Based on the README examples, the library follows a Guava-like API design to make it familiar to developers.
- Extensibility: With numerous integration points (e.g., JCache, Guava, Scala wrappers), the design is heavily oriented toward extending and adapting the core functionality.

##### Relevant Technologies
- Java (with multi-module Gradle builds)
- Testing frameworks and benchmarking tools (JMH for performance benchmarks, extensive test suites under src/test)
- Integration with external CI services (GitHub Actions, CircleCI, etc.)
- Documentation and artifact publishing mechanisms (Maven Central badges in the README, javadoc generation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Build("Build & CI/CD"):::infrastructure
    Core("Core Caching Library (caffeine)"):::core
    Guava("Guava Adapter"):::adapter
    JCache("JCache Adapter"):::adapter
    Simulator("Simulator"):::simulation
    Examples("Example Projects"):::examples

    %% Relationships to Core Caching Library
    Guava -->|"adapts"| Core
    JCache -->|"adapts"| Core
    Simulator -->|"simulates"| Core
    Examples -->|"uses"| Core

    %% Build & CI/CD integrates all modules
    Build -->|"builds"| Core
    Build -->|"builds"| Guava
    Build -->|"builds"| JCache
    Build -->|"builds"| Simulator
    Build -->|"builds"| Examples

    %% Click Events
    click Core "https://github.com/ben-manes/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache"
    click Guava "https://github.com/ben-manes/caffeine/tree/master/guava/src/main/java/com/github/benmanes/caffeine/guava"
    click JCache "https://github.com/ben-manes/caffeine/tree/master/jcache/src/main/java/com/github/benmanes/caffeine/jcache"
    click Simulator "https://github.com/ben-manes/caffeine/tree/master/simulator/src/main/java/com/github/benmanes/caffeine/cache/simulator"
    click Examples "https://github.com/ben-manes/caffeine/tree/master/examples"
    click Build "https://github.com/ben-manes/caffeine/blob/master/build.gradle.kts"

    %% Styles
    classDef core fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef adapter fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef simulation fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef examples fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#cceeff,stroke:#333,stroke-width:2px;
```
