# landry5/caffeine architecture

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

- Interactive diagram: https://gitdiagram.com/landry5/caffeine
- Repository: https://github.com/landry5/caffeine

## Overview

##### Project type and purpose
- This is a Java-based, multi-module library (“Caffeine”) providing a high-performance in-memory cache.
- Modules include:
– core cache engine (“caffeine”)
– adapters (“guava” and “jcache”)
– a trace-driven simulator (“simulator”)
– example clients under “examples/…”
- Build and CI/CD infrastructure is defined via Gradle scripts, custom plugins, and GitHub Actions.

##### File structure
- Top-level: a root Gradle project (settings.gradle.kts)
- Submodules: caffeine/, guava/, jcache/, simulator/, plus examples/ and gradle/plugins/
- Build scripts: build.gradle.kts at root, per-module builds, shared versioning in gradle/libs.versions.toml
- CI/CD: GitHub workflows (.github/workflows/*.yml), custom Gradle plugins (gradle/plugins), shell scripts (.github/scripts)

##### README highlights
- Core features: loading cache, size-based eviction, time-based expiration, async refresh, reference eviction, listeners, write-through, stats
- Extensions: JSR-107 (JCache), Guava compatibility, simulator
- Integration targets: Spring, Micronaut, Quarkus, Kafka, etc.

##### Main components
a. Client application(s): calls into the caching API
b. Caffeine core module:
– CacheBuilder → LocalCacheFactory → LocalCache
– Eviction mechanisms (FrequencySketch, Pacer, TimerWheel)
– Expiration (Ticker, Expiry policy)
– Concurrency (MpscGrowableArrayQueue, StripedBuffer)
– Statistics (StatsCounter implementations)
c. Extension modules:
– Guava adapter wraps core for Guava-style API
– JSR-107 adapter implements javax.cache.spi.CachingProvider on top of core
d. Simulator module:
– TraceReader(s) ingest external traces
– Admission policies (TinyLFU, CountMin, etc.) reuse core eviction logic
– Policy components register via a registry and produce Reports
e. Build infrastructure:
– Gradle root + plugins, shared configuration
– GitHub Actions CI pipeline
– Code generation (javaPoet in caffeine/src/javaPoet)

##### Relationships and interactions
- Client → Caffeine API → Core module
- Core module provides pluggable eviction/expiration/statistics internals
- Extensions depend on core and present alternate API layers
- Simulator depends on core eviction/expiry/policy implementations to evaluate performance
- Examples depend on core and extensions, demonstrating usage
- Gradle plugins apply across modules to standardize build/test quality
- CI/CD pipelines invoke Gradle tasks for build, test, benchmarks, security scans

##### Architectural patterns and design principles
- Modular multi-project structure (separation of core, adapters, simulation, examples)
- Pluggable components via factory and registry patterns (NodeFactory, PolicyRegistry)
- Code-generation at build time (javaPoet) for local cache implementations
- Single responsibility within modules: core engine vs API adapters vs simulator
- Extensive testing and benchmarking modules (jcstress, jmh, simulator, tests under each module)

##### Technologies, frameworks, and libraries
- Java 11+ (uses module-info.java)
- Gradle Kotlin DSL for builds and custom plugins
- GitHub Actions, Dependabot, Qodana, Snyk for CI/quality/security
- JMH and JCStress for benchmarks and concurrency stress tests
- javaPoet for code generation of cache variants

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Applications
    subgraph "Examples" 
        Examples["Examples (Client Apps)"]:::examples
    end

    %% Adapter Modules
    subgraph "Adapter Modules"
        GuavaAdapter["Guava Adapter"]:::adapter
        JCacheAdapter["JCache (JSR-107) Adapter"]:::adapter
    end

    %% Core Module
    subgraph "Caffeine Core Module"
        CoreAPI["CacheBuilder / Core API"]:::core
        subgraph "Eviction Mechanisms"
            FrequencySketch["FrequencySketch"]:::core
            Pacer["Pacer"]:::core
            TimerWheel["TimerWheel"]:::core
            StripedBuffer["StripedBuffer"]:::core
            MpscQueue["MpscGrowableArrayQueue"]:::core
        end
        subgraph "Expiration & Factory"
            Ticker["Ticker"]:::core
            Expiry["Expiry Policy"]:::core
            Scheduler["Scheduler"]:::core
            LocalFactory["LocalCacheFactory"]:::core
            LocalCache["LocalCache"]:::core
        end
        subgraph "Statistics"
            StatsCounter["StatsCounter Implementations"]:::core
        end
        CodeGen["Code Generation (javaPoet)"]:::core
    end

    %% Simulator Module
    subgraph "Simulator Module"
        SimulatorCore["Simulator Entrypoints"]:::simulator
        subgraph "Trace Readers"
            TraceReaders["TraceReader(s)"]:::simulator
        end
        subgraph "Admission Policies"
            AdmissionPolicies["Admission Policies"]:::simulator
        end
        PolicyRegistry["Policy Registry / Actors"]:::simulator
        subgraph "Reporters"
            Reporters["Reporters (Text, CSV, Table)"]:::simulator
        end
    end

    %% Build Infrastructure
    subgraph "Build Infrastructure"
        GradleRoot["Root Gradle Scripts"]:::infra
        VersionCatalog["Version Catalog (.toml)"]:::infra
        CustomPlugins["Custom Gradle Plugins"]:::infra
    end

    %% CI/CD
    subgraph "CI/CD Pipelines"
        Workflows["GitHub Actions Workflows"]:::cicd
        Scripts["CI Helper Scripts"]:::cicd
    end

    %% Relationships
    Examples -->|"uses"| GuavaAdapter
    Examples -->|"uses"| JCacheAdapter
    Examples -->|"uses"| CoreAPI
    GuavaAdapter -->|"wraps"| CoreAPI
    JCacheAdapter -->|"wraps"| CoreAPI
    SimulatorCore -->|"depends on"| FrequencySketch
    SimulatorCore -->|"depends on"| AdmissionPolicies
    SimulatorCore -->|"generates Reports via"| Reporters
    AdmissionPolicies -->|"reuse eviction logic in"| FrequencySketch
    PolicyRegistry -->|"registers policies for"| SimulatorCore

    GradleRoot -->|applies to| GuavaAdapter
    GradleRoot -->|applies to| JCacheAdapter
    GradleRoot -->|applies to| CoreAPI
    GradleRoot -->|applies to| SimulatorCore
    CustomPlugins -->|enhance build of| GradleRoot
    VersionCatalog -->|shared versions for| GradleRoot

    Workflows -->|"executes Gradle tasks on"| GradleRoot
    Scripts -->|"support CI jobs for"| Workflows

    %% Click Events
    click Examples "https://github.com/landry5/caffeine/tree/master/examples/"
    click CoreAPI "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click CodeGen "https://github.com/landry5/caffeine/tree/master/caffeine/src/javaPoet/java/com/github/benmanes/caffeine/cache/"
    click FrequencySketch "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click Pacer "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click TimerWheel "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click StripedBuffer "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click MpscQueue "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click Ticker "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click Expiry "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click Scheduler "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click LocalFactory "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click LocalCache "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/"
    click StatsCounter "https://github.com/landry5/caffeine/tree/master/caffeine/src/main/java/com/github/benmanes/caffeine/cache/stats/"
    click GuavaAdapter "https://github.com/landry5/caffeine/tree/master/guava/src/main/java/com/github/benmanes/caffeine/guava/"
    click JCacheAdapter "https://github.com/landry5/caffeine/tree/master/jcache/src/main/java/com/github/benmanes/caffeine/jcache/"
    click SimulatorCore "https://github.com/landry5/caffeine/tree/master/simulator/src/main/java/com/github/benmanes/caffeine/cache/simulator/"
    click AdmissionPolicies "https://github.com/landry5/caffeine/tree/master/simulator/src/main/java/com/github/benmanes/caffeine/cache/simulator/admission/"
    click TraceReaders "https://github.com/landry5/caffeine/tree/master/simulator/src/main/java/com/github/benmanes/caffeine/cache/simulator/parser/"
    click PolicyRegistry "https://github.com/landry5/caffeine/tree/master/simulator/src/main/java/com/github/benmanes/caffeine/cache/simulator/policy/"
    click Reporters "https://github.com/landry5/caffeine/tree/master/simulator/src/main/java/com/github/benmanes/caffeine/cache/simulator/report/"
    click GradleRoot "https://github.com/landry5/caffeine/blob/master/build.gradle.kts"
    click VersionCatalog "https://github.com/landry5/caffeine/blob/master/gradle/libs.versions.toml"
    click CustomPlugins "https://github.com/landry5/caffeine/tree/master/gradle/plugins/src/main/kotlin/"
    click Workflows "https://github.com/landry5/caffeine/tree/master/.github/workflows/"
    click Scripts "https://github.com/landry5/caffeine/tree/master/.github/scripts/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#21618C,color:#1B4F72
    classDef adapter fill:#A9DFBF,stroke:#239B56,color:#196F3D
    classDef simulator fill:#F5CBA7,stroke:#B9770E,color:#7E5109
    classDef infra fill:#D5D8DC,stroke:#566573,color:#2E4053
    classDef cicd fill:#D5D8DC,stroke:#283747,color:#1C2833
    classDef examples fill:#A3E4D7,stroke:#148F77,color:#0E6251
```
