# whatyouhide/redix architecture

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

- Interactive diagram: https://gitdiagram.com/whatyouhide/redix
- Repository: https://github.com/whatyouhide/redix

## Overview

##### Project type and purpose
- Type: an open-source Elixir library (Redis client)
- Purpose: provide a fast, pipelined, resilient interface for sending commands and Pub/Sub messages to Redis (including support for SSL and Sentinel)

##### File structure
- Top-level files: mix.exs (project config), docker-compose.yml (test harness), pages/ (extended docs), lib/redix/ (source code), test/ (unit & integration tests with Docker)
- lib/redix/ contains:
– connection.ex       (GenServer that manages one Redis connection)
– connector.ex       (module to open TCP/SSL sockets, handle reconnections)
– protocol.ex        (encode/decode RESP wire protocol)
– format.ex          (translate Elixir command lists to RESP frames)
– socket_owner.ex    (process that exclusively owns the socket)
– start_options.ex   (validate and normalize user options)
– uri.ex             (parse Redis & Sentinel URIs)
– telemetry.ex       (emit events for command latencies, errors, reconnections)
– exceptions.ex      (custom error types)
– pubsub/ folder     (Redix.PubSub implementation, separate connection, subscribe/publish logic)
- test/docker/ defines Redis & Sentinel setups used by the test suite (ACL, auth, sentinel scenarios)

##### Inspect the README for additional insights
- Describes features: pipelining, automatic reconnection with backoff, Pub/Sub, SSL, Sentinel support
- Usage: Redix.start_link / Redix.command / Redix.pipeline / Redix.PubSub APIs
- Advises using docker-compose for spinning up Redis instances when running tests

##### Main components
- Redis primary instance
- Zero or more Redis replicas
- Sentinel cluster (one or more instances)
- Redix Connection GenServer
– uses Connector → opens TCP/SSL socket to Redis or Sentinel
– uses Protocol & Format to encode/decode commands & replies
– owns a socket via SocketOwner process
– publishes metrics via Telemetry
- Redix.PubSub GenServer (similar structure to Connection, but handles subscription messages and incoming events)
- Top-level Supervisor
– children: Connection processes, PubSub processes

- User API → Connection GenServer : call Redix.command/2 or pipeline/2
- Connection → Connector : socket_open(host, port, opts)
- Connector → TCP/SSL socket : connect, send binary frames
- Connection → Protocol.decode(stream) : parse RESP replies
- Connection → Telemetry : emit start/stop events, errors, reconnections
- PubSub GenServer ↔ Redis server : SUBSCRIBE commands & async message pushes
- Connection on disconnect → Connector : retry with exponential backoff
- When using Sentinel → Connector contacts Sentinel URIs → sends SENTINEL get-master-addr-by-name → discovers primary → (re)connects to primary

##### Architectural patterns & design principles
- OTP supervision: each connection and PubSub runs under a supervisor for automatic restart
- Separation of concerns: connector (transport), protocol (wire format), format (command shaping), telemetry (metrics)
- Resiliency: built-in reconnection strategy with configurable backoff
- Extensibility: start_options and URI parsing allow plugging SSL or custom transports

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External systems
    Redis["Redis Primary"]:::external
    Replica["Redis Replica"]:::external
    Sentinel["Sentinel Cluster"]:::external

    %% Elixir Client components
    subgraph "Elixir Client"
        subgraph "Supervisor"
            Conn["Redix Connection GenServer"]:::otp
            PubSubConn["Redix.PubSub GenServer"]:::otp
        end
        Connector["Connector (TCP/SSL & Reconnect)"]:::helper
        Protocol["Protocol (RESP Encode/Decode)"]:::helper
        Format["Format (Command → RESP)"]:::helper
        SocketOwner["SocketOwner Process"]:::otp
        StartOptions["StartOptions Validator"]:::helper
        URI["URI Parser (Redis/Sentinel)"]:::helper
        Telemetry["Telemetry (Events & Metrics)"]:::helper
        Exceptions["Exceptions (Error Types)"]:::helper
    end

    %% Interactions
    Conn -->|"socket_open(host,port,opts)"| Connector
    Connector -->|"connect/send binary"| Redis
    Connector -->|"discover master"| Sentinel
    Connector -->|"reconnect (backoff)"| Redis
    Conn -->|"encode command"| Format
    Conn -->|"send RESP"| Protocol
    Protocol -->|"decode reply"| Conn
    Conn -->|"own socket"| SocketOwner
    Conn -->|"emit start/stop,errors"| Telemetry
    Conn -->|"validate opts"| StartOptions
    Connector -->|"parse URI"| URI
    Conn -->|"raise error"| Exceptions

    PubSubConn -->|"SUBSCRIBE/PUBLISH"| Redis
    Redis -->|"message push"| PubSubConn

    %% Test & Config
    mix["Project Config"]:::config
    compose["Docker-Compose Harness"]:::config
    tests["Test Docker Setups"]:::config

    mix -->|"build/start"| Conn
    compose --> tests

    %% Click Events
    click Conn "https://github.com/whatyouhide/redix/blob/main/lib/redix/connection.ex"
    click Connector "https://github.com/whatyouhide/redix/blob/main/lib/redix/connector.ex"
    click Protocol "https://github.com/whatyouhide/redix/blob/main/lib/redix/protocol.ex"
    click Format "https://github.com/whatyouhide/redix/blob/main/lib/redix/format.ex"
    click SocketOwner "https://github.com/whatyouhide/redix/blob/main/lib/redix/socket_owner.ex"
    click StartOptions "https://github.com/whatyouhide/redix/blob/main/lib/redix/start_options.ex"
    click URI "https://github.com/whatyouhide/redix/blob/main/lib/redix/uri.ex"
    click Telemetry "https://github.com/whatyouhide/redix/blob/main/lib/redix/telemetry.ex"
    click Exceptions "https://github.com/whatyouhide/redix/blob/main/lib/redix/exceptions.ex"
    click PubSubConn "https://github.com/whatyouhide/redix/blob/main/lib/redix/pubsub/connection.ex"
    click mix "https://github.com/whatyouhide/redix/blob/main/mix.exs"
    click compose "https://github.com/whatyouhide/redix/blob/main/docker-compose.yml"
    click tests "https://github.com/whatyouhide/redix/tree/main/test/docker/**"

    %% Styles
    classDef otp fill:#9f6,stroke:#383,stroke-width:2px
    classDef helper fill:#f96,stroke:#b63,stroke-width:2px
    classDef external fill:#6bf,stroke:#039,stroke-width:2px
    classDef config fill:#ccc,stroke:#999,stroke-width:2px
```
