# redis/node-redis architecture

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

- Interactive diagram: https://gitdiagram.com/redis/node-redis
- Repository: https://github.com/redis/node-redis

## Overview

##### Project type and purpose
- This is an open-source, multi-package Node.js client library (“Node-Redis”) for interacting with Redis and Redis-Stack modules.
- Its purpose is to expose a high-performance API (in JavaScript/TypeScript) that developers use to send commands, transactions, pub/sub, auto-pipelining, clustering, and use Redis modules (Bloom, JSON, Search, Time-Series) as well as token-based auth via Microsoft Entra ID (entraid).

##### File structure
- Top level
- CI/CD and linting configs (.github/, .deepsource.toml)
- Docs (docs/), examples (examples/), benchmarks (benchmark/)
- Monorepo package manifests (package.json, tsconfig.base.json)
- packages/
- packages/redis – “all-in-one” client
- packages/client – core client (RedisClient, RedisCluster, pools, RESP encoder/decoder, command queue, socket)
- packages/bloom, json, search, time-series – individual Redis-Stack modules, each providing command definitions and specs
- packages/entraid – token-based auth provider for Microsoft Entra ID
- packages/test-utils – Docker helpers and test harness
- Each package includes command-by-command TS files, specs, tsconfig, and release configs.

##### README for additional insights
- Confirms multi-package layout and capabilities: connection, CLI, commands, modifiers, transactions, pub/sub, scan iterators, events.
- Highlights plug-and-play of modules (install only subsets if desired).
- Mentions auto-pipelining, pooling, cluster support, and programmability (Lua scripts).

a. Main components
- User Application (any Node.js process using `import { createClient } from "redis"`)
- Core Client Library (packages/client & packages/redis)
– API Layer (RedisClient, RedisCluster, createClientPool)
– Command Registry & Transformers (generic-transformers, command factories)
– Transport Layer
· Socket Manager (TCP/TLS handshake)
· RESP Encoder/Decoder (parser + serializer)
– Connection Pool (RedisClientPool / IsolationPool)
– Event Emitter (connect, ready, error, etc.)
- Redis-Stack Module Plugins (bloom, json, search, time-series)
- Authentication Module (entraid → token manager + Azure/MSAL identity provider)
- Redis Server(s) – single instance or Cluster nodes
- External Services
– NPM Registry (for package distribution)
– Azure AD (for entraid flows)
– Docker (for local Redis in examples/tests)
b. Relationships & interactions
1. App calls Core API →
2. API enqueues commands in Command Queue →
3. Transport Layer serializes via RESP Encoder →
4. Socket writes to Redis Server over TCP/TLS →
5. Redis executes & responds in RESP →
6. Socket reads, passes bytes to RESP Decoder →
7. Decoder emits structured reply →
8. Command Transformers convert to JS types/promises →
9. API returns data to App
- Modules (Bloom/JSON/etc.) register additional commands in the registry; entraid intercepts the connection setup to inject AUTH tokens.
- Pooling spawns multiple socket connections under the hood for blocking commands.
- Clustering logic auto-discovers cluster slots and routes commands to the correct node.
c. Architectural patterns & design principles
- Modular plugin architecture (each Redis-Stack feature is a separate package)
- Command pattern (each Redis command is encapsulated in its own TS file with spec + transformer)
- Factory/builder for client instantiation (`createClient`, `createClientPool`)
- Observer pattern for network events (EventEmitter)
- Monorepo management (TypeScript project references, shared base configs)
d. Key technologies
- Node.js & TypeScript
- RESP protocol over TCP/TLS
- NPM/Yarn monorepo (multiple `package.json`, release-it, nyc for coverage)
- Azure identity via MSAL (in `entraid`)
- Docker for local Redis & integration tests
- GitHub Actions for CI and release drafter

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    subgraph "User Application"
        App["User Application"]:::app
    end

    %% Core Client Library
    subgraph "Core Client Library"
        direction TB
        API["Core API Layer\n(RedisClient, RedisCluster,\ncreateClientPool)"]:::core
        AllInOne["All-in-One Client\n(createClient + plugins)"]:::core
        Pool["Connection Pool\n(RedisClientPool)"]:::core
        Queue["Command Queue"]:::core
        Registry["Command Registry\n& Transformers"]:::core
        CommandsDefs["Core Redis Command Definitions"]:::core
        ClusterIndex["Cluster Logic\n(index)"]:::core
        ClusterSlots["Cluster Slots\n(discovery)"]:::core
        Lua["Lua Scripting Support"]:::core
        subgraph TransportLayer["Transport Layer"]
            direction TB
            Encoder["RESP Encoder"]:::core
            Decoder["RESP Decoder"]:::core
            Socket["Socket Manager"]:::core
        end
    end

    %% Module Plugins
    subgraph "Module Plugins"
        direction TB
        Bloom["Bloom Module"]:::module
        JSON["JSON Module"]:::module
        Search["Search Module"]:::module
        TS["Time-Series Module"]:::module
        subgraph "Authentication Module"
            direction TB
            CredProv["Entraid Credentials\nProvider"]:::module
            AzureProv["Azure Identity\nProvider"]:::module
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Redis["Redis Server(s)"]:::external
        AzureAD["Azure AD"]:::external
        NPM["NPM Registry"]:::external
        Docker["Docker"]:::external
    end

    %% Test & Examples
    subgraph "Test & Examples"
        direction TB
        TestUtils["Test Utilities"]:::util
        Examples["Examples"]:::util
        Benchmark["Benchmark Harness"]:::util
    end

    %% Connections
    App -->|"createClient()/commands"| API
    API -->|"enqueue"| Queue
    Queue -->|"serialize"| Encoder
    Encoder -->|"write"| Socket
    Socket -->|"TCP/TLS"| Redis
    Redis -->|"RESP bytes"| Socket
    Socket -->|"parse"| Decoder
    Decoder -->|"emit reply"| Registry
    Registry -->|"transform"| API
    API -->|"response"| App

    AllInOne --> API

    Bloom --> Registry
    JSON --> Registry
    Search --> Registry
    TS --> Registry

    CredProv -->|inject AUTH token| Socket
    AzureAD --> CredProv

    API -->|"cluster slot routing"| ClusterIndex
    ClusterIndex --> ClusterSlots
    ClusterSlots --> Socket

    API -->|"eval scripts"| Lua
    Lua --> Socket

    TestUtils --> Docker
    Docker --> Redis
    Examples --> App
    Benchmark --> App

    API -->|"publish"| NPM

    %% Click events
    click API "https://github.com/redis/node-redis/blob/master/packages/client/lib/client/index.ts"
    click AllInOne "https://github.com/redis/node-redis/blob/master/packages/redis/index.ts"
    click Pool "https://github.com/redis/node-redis/blob/master/packages/client/lib/client/pool.ts"
    click Queue "https://github.com/redis/node-redis/blob/master/packages/client/lib/client/commands-queue.ts"
    click Encoder "https://github.com/redis/node-redis/blob/master/packages/client/lib/RESP/encoder.ts"
    click Decoder "https://github.com/redis/node-redis/blob/master/packages/client/lib/RESP/decoder.ts"
    click Socket "https://github.com/redis/node-redis/blob/master/packages/client/lib/client/socket.ts"
    click Registry "https://github.com/redis/node-redis/blob/master/packages/client/lib/commands/generic-transformers.ts"
    click CommandsDefs "https://github.com/redis/node-redis/tree/master/packages/client/lib/commands/"
    click ClusterIndex "https://github.com/redis/node-redis/blob/master/packages/client/lib/cluster/index.ts"
    click ClusterSlots "https://github.com/redis/node-redis/blob/master/packages/client/lib/cluster/cluster-slots.ts"
    click Lua "https://github.com/redis/node-redis/blob/master/packages/client/lib/lua-script.ts"
    click CredProv "https://github.com/redis/node-redis/blob/master/packages/entraid/lib/entraid-credentials-provider.ts"
    click AzureProv "https://github.com/redis/node-redis/blob/master/packages/entraid/lib/azure-identity-provider.ts"
    click Bloom "https://github.com/redis/node-redis/blob/master/packages/bloom/lib/index.ts"
    click JSON "https://github.com/redis/node-redis/blob/master/packages/json/lib/index.ts"
    click Search "https://github.com/redis/node-redis/blob/master/packages/search/lib/index.ts"
    click TS "https://github.com/redis/node-redis/blob/master/packages/time-series/lib/index.ts"
    click TestUtils "https://github.com/redis/node-redis/blob/master/packages/test-utils/lib/index.ts"
    click Examples "https://github.com/redis/node-redis/tree/master/examples/"
    click Benchmark "https://github.com/redis/node-redis/blob/master/benchmark/lib/index.js"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#3399FF,stroke-width:2px;
    classDef module fill:#E6F9E6,stroke:#2EB82E,stroke-width:2px;
    classDef external fill:#FFE6CC,stroke:#FF9900,stroke-width:2px;
    classDef app fill:#F0F0F0,stroke:#999999,stroke-width:2px;
    classDef util fill:#E8E8E8,stroke:#666666,stroke-width:2px;
```
