# lettuce-io/lettuce-core architecture

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

- Interactive diagram: https://gitdiagram.com/lettuce-io/lettuce-core
- Repository: https://github.com/lettuce-io/lettuce-core

## Overview

##### Project type and purpose
- Lettuce is an open-source, advanced Java client library for Redis. It is not a full-stack application but a modular library intended to be embedded in Java/Kotlin applications. Its purpose is to provide synchronous, asynchronous, reactive and coroutine-based APIs for interacting with Redis, including support for Sentinel, Cluster, pipelining, SSL, codecs, and streaming.

##### File structure analysis
- Top-level build and Docs
- pom.xml, Makefile, mkdocs.yml, README.md, docs/ – build configuration and documentation.
- Core library code under src/main/java/io/lettuce/core and src/main/kotlin/io/lettuce
- api/ – high-level command interfaces (sync, async, reactive, push)
- protocol/ – command encoding/decoding, state machine, connection handling
- codec/ – data‐type codecs (StringCodec, ByteArrayCodec, JSON, etc.)
- cluster/, sentinel/, masterreplica/, masterslave/ – HA and sharding logic
- dynamic/ – runtime command factory for generated command interfaces
- resource/ – Netty event-loop and transport resources
- event/ – event bus and event model for connection/command events
- reactive, coroutines extensions, Kotlin wrappers under src/main/kotlin
- Tests and examples under src/test – integration tests requiring Redis instances (docker-env), unit tests, JMH benchmarks, examples.

##### README insights
- Highlights synchronous, asynchronous, reactive and coroutine APIs.
- Emphasizes support for Sentinel, Cluster, SSL, Unix domain sockets, streaming, CDI, codecs, Netty transport.
- Points to user guide sections for each major feature.

##### Main components
a. User Application
– Uses one or more Lettuce API variants: Sync, Async, Reactive (Reactor), Coroutines.
b. API Layer
– Command interfaces (io.lettuce.core.api.sync, async, reactive, coroutines).
c. Connection & Client
– RedisClient / RedisClusterClient / RedisSentinelClient objects manage connection creation.
– StatefulRedisConnection or StatefulRedisClusterConnection abstractions.
d. Dynamic Command Factory
– Builds command invocations at runtime, dispatching into protocol layer.
e. Protocol Layer
– CommandEncoder / CommandHandler / RedisStateMachine handle serialization, framing, RESP protocol.
f. Netty Transport & Resource Manager
– ClientResources and EventLoopResources wrap Netty’s EventLoopGroup, native transports (epoll, kqueue).
– Netty channel handlers (RedisChannelHandler) manage I/O.
g. HA / Sharding Manager
– ClusterTopologyRefresh, MasterReplicaConnector, SentinelTopologyRefresh detect and react to topology changes.
h. Codec Layer
– RedisCodec and ComposedRedisCodec for marshalling key/value types.
i. Event Bus
– Publishes connection, command, metrics, JFR events for instrumentation and listeners.
j. External Services
– Redis server instances (standalone, Sentinel, Cluster), Docker-based test instances.

##### Component interactions and data flow
1. Application invokes a command on the API interface.
2. API delegates to Dynamic Command Factory → generates a Command object.
3. Command passes to Protocol Layer → CommandEncoder wraps into RedisCommand message.
4. Netty Transport sends the message over TCP/SSL/Unix socket to Redis server(s).
5. Server responds; Netty pipeline decodes the RESP frame via CommandHandler → back to Protocol Layer.
6. Protocol Layer completes the Future/Mono or blocks for sync, yielding the result to application.
7. For Cluster/Sentinel: HA Manager intercepts connection requests and topology refresh commands; routes commands to correct node(s).
8. Codecs transform between raw bytes and application types.
9. Event Bus publishes lifecycle and metrics events to registered listeners.

##### Architectural patterns and design principles
- Layered architecture: API → Dynamic Factory → Protocol → Transport → External
- Separation of concerns: codecs, clustering logic, eventing, resource management are decoupled.
- Extension points: dynamic API generation, event bus, custom codecs, CDI integration.
- Reactive/non-blocking by default, providing back-pressure support via Reactor or Kotlin coroutines.
- Resilience: auto-reconnect and topology refresh for Sentinel/Cluster.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Application
    App["User Application"]:::external

    %% API Layer
    subgraph "API Layer" 
        APILayer["API Layer\n(io.lettuce.core.api)"]:::api
        KotlinAPI["Kotlin Extensions &\nCoroutines API"]:::api
    end

    %% Client Managers
    subgraph "Client Managers" 
        ConnMgr["RedisClient & Connection Manager"]:::client
        ClusterClient["RedisClusterClient"]:::client
        SentinelClient["RedisSentinelClient"]:::client
    end

    %% Core Processing
    DynamicFactory["Dynamic Command Factory"]:::core
    Protocol["Protocol Layer\n(Encoder/Handler/StateMachine)"]:::protocol
    Codec["Codec Layer\n(RedisCodec & ComposedRedisCodec)"]:::protocol

    %% Transport Layer
    subgraph "Transport & Resources"
        Transport["Netty Transport &\nClientResources"]:::transport
        ChannelHandler["RedisChannelHandler"]:::transport
    end

    %% HA & Sharding
    subgraph "HA / Sharding Manager" 
        HACluster["ClusterTopologyRefresh"]:::ha
        HAMaster["MasterReplicaConnector"]:::ha
    end

    %% Eventing
    EventBus["Event Bus & Publisher"]:::event

    %% External Services
    RedisServer["Redis Servers\n(Standalone, Cluster, Sentinel)"]:::external
    TestServices["External Test Services\n(docker-env)"]:::external

    %% Data Flow
    App -->|"invokes API"| APILayer
    App -->|"invokes API"| KotlinAPI
    APILayer -->|"delegates to"| DynamicFactory
    KotlinAPI -->|"delegates to"| DynamicFactory
    DynamicFactory -->|"generates Command"| Protocol
    Protocol -->|"uses Codec"| Codec
    Protocol -->|"ENCODE →"| ChannelHandler
    ChannelHandler -->|"send over TCP/SSL"| RedisServer
    RedisServer -->|"RESP frame"| ChannelHandler
    ChannelHandler -->|"DECODE →"| Protocol
    Protocol -->|"completes Future/Mono"| APILayer
    Protocol -->|"completes Future/Mono"| KotlinAPI
    %% HA routing
    HACluster --> Protocol
    HACluster --> ChannelHandler
    HAMaster --> Protocol
    HAMaster --> ChannelHandler
    %% Event Bus
    Protocol --> EventBus
    Transport --> EventBus

    %% Click Events
    click APILayer "https://github.com/lettuce-io/lettuce-core/tree/main/src/main/java/io/lettuce/core/api"
    click KotlinAPI "https://github.com/lettuce-io/lettuce-core/tree/main/src/main/kotlin/io/lettuce/core/api"
    click ConnMgr "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/RedisClient.java"
    click ClusterClient "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/cluster/RedisClusterClient.java"
    click SentinelClient "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/sentinel/RedisSentinelAsyncCommandsImpl.java"
    click SentinelClient "https://github.com/lettuce-io/lettuce-core/tree/main/src/main/java/io/lettuce/core/sentinel/api"
    click DynamicFactory "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/dynamic/CommandFactory.java"
    click Protocol "https://github.com/lettuce-io/lettuce-core/tree/main/src/main/java/io/lettuce/core/protocol"
    click Transport "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/resource/ClientResources.java"
    click ChannelHandler "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/RedisChannelHandler.java"
    click HACluster "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/cluster/topology/ClusterTopologyRefresh.java"
    click HAMaster "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/masterreplica/MasterReplicaConnector.java"
    click Codec "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/codec/RedisCodec.java"
    click EventBus "https://github.com/lettuce-io/lettuce-core/blob/main/src/main/java/io/lettuce/core/event/DefaultEventBus.java"
    click TestServices "https://github.com/lettuce-io/lettuce-core/tree/main/src/test/resources/docker-env"

    %% Styles
    classDef api fill:#bbdefb,stroke:#2196f3,color:#0d47a1
    classDef client fill:#b3e5fc,stroke:#0288d1,color:#01579b
    classDef core fill:#c5cae9,stroke:#3f51b5,color:#1a237e
    classDef protocol fill:#c8e6c9,stroke:#4caf50,color:#1b5e20
    classDef transport fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef ha fill:#e1bee7,stroke:#9c27b0,color:#4a148c
    classDef event fill:#d7ccc8,stroke:#8d6e63,color:#3e2723
    classDef external fill:#eeeeee,stroke:#9e9e9e,color:#424242
```
