# joyieldinc/predixy architecture

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

- Interactive diagram: https://gitdiagram.com/joyieldinc/predixy
- Repository: https://github.com/joyieldinc/predixy

## Overview

##### Project Type and Purpose
- Predixy is an open-source, high-performance, C++-based proxy server for Redis Sentinel and Redis Cluster deployments.
- It sits between Redis clients and backend Redis instances, providing connection multiplexing, load balancing, command routing, authentication, stats, and latency monitoring.

##### File Structure Analysis
- Top-level:
- conf/ — configuration files (predixy.conf references auth.conf, cluster.conf, sentinel.conf, etc.)
- doc/ — markdown docs and benchmarks
- src/ — core C++ implementation
- test/ — Python tests
- Makefile, _config.yml (for GitHub pages)
- src/:
- main.cpp — entry point
- Conf(.cpp/.h), ConfParser — load and parse config files
- AcceptConnection/Socket, ListenSocket — frontend acceptor
- ConnectConnection/Pool, ConnectSocket — backend connector pools
- Multiplexors (Epoll, Kqueue, Poll) — event-loop/Reactor pattern
- Command, RequestParser, ResponseParser — protocol parsing
- Proxy, Handler — request routing and response dispatch
- ClusterServerPool, SentinelServerPool, StandaloneServerPool — backend server management
- Distribution, Crc16, DC — sharding/load balancing logic (cluster slot, multi-DC)
- Auth — ACL enforcement
- LatencyMonitor, Stats — metrics collection
- Logger, LogFileSink — logging

##### Key Architectural Patterns and Principles
- Reactor pattern (I/O multiplexing per thread)
- Thread-per-core or configurable multi-threading (MT=true/false)
- Connection pooling for backend servers
- Pluggable dispatch for Redis Cluster vs Sentinel vs standalone
- Non-blocking I/O, event-driven design
- Modular separation of concerns: config, parsing, networking, routing, monitoring

##### Main Components
A. Predixy Core
1. Configuration Manager
- Loads predixy.conf and subsidiary files (auth.conf, cluster.conf, etc.)
2. Frontend Listener
- ListenSocket → AcceptConnection → assigns client sockets to Worker Threads
3. Worker Threads (one or more)
- Each with a Multiplexor (epoll/poll/kqueue)
- Handles ClientConnection lifecycle: parse requests, enforce Auth, route via Proxy
4. Proxy & Routing Layer
- CommandParser/RequestParser → selects appropriate ServerPool
- Distribution/Crc16 (for cluster slot) or DC-based routing
5. Backend Connector Pools
- ConnectConnectionPool manages persistent connections to each Redis node
- Separate pools for cluster nodes, sentinel masters/slaves, standalone instances
6. Response Handling
- ResponseParser → write back to client connections
7. Monitoring & Logging
- LatencyMonitor tracks per-command latency
- Stats exposes INFO interface
- Logger asynchronously writes logs, rotates by time/size

B. External Entities
- Redis Cluster nodes
- Redis Sentinel masters/slaves
- Redis standalone group(s)
- Clients (redis-cli, applications)

##### Data Flow and Interactions
1. Startup
- Main reads configuration → initializes ServerPools and WorkerThreads
2. Client Request
- Client → ListenSocket → AcceptConnection → WorkerThread.Multiplexor
- Parse request → Auth check → Proxy
3. Routing
- Proxy uses Distribution or Sentinel logic to pick backend(s)
- Acquire ConnectConnection from ConnectConnectionPool
- Send raw Redis protocol to backend
4. Backend Response
- Backend → ConnectSocket → WorkerThread.Multiplexor
- ResponseParser → Proxy/Handler → write to ClientConnection
- Update LatencyMonitor, Stats
5. Metrics
- Clients issue INFO command → Stats subsystem returns predixy metrics

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Config
    Config["Configuration Manager"]:::configgray
    click Config "https://github.com/joyieldinc/predixy/tree/master/conf/"

    %% Clients
    Clients["Clients (redis-cli, apps)"]:::external

    %% Frontend Listener
    Listener["Frontend Listener\n(ListenSocket → AcceptConnection)"]:::networkingblue
    click Listener "https://github.com/joyieldinc/predixy/blob/master/src/ListenSocket.cpp"

    %% Worker Threads
    subgraph "Worker Threads (n)"
        direction TB
        Multiplexor["Multiplexor\n(epoll/poll/kqueue)"]:::networkingblue
        click Multiplexor "https://github.com/joyieldinc/predixy/blob/master/src/Multiplexor.h"
        ReqParser["RequestParser"]:::parsinggreen
        click ReqParser "https://github.com/joyieldinc/predixy/blob/master/src/RequestParser.cpp"
        Auth["Auth Enforcement"]:::parsinggreen
        click Auth "https://github.com/joyieldinc/predixy/blob/master/conf/auth.conf"
        Proxy["Proxy & Routing"]:::parsinggreen
        click Proxy "https://github.com/joyieldinc/predixy/blob/master/src/Proxy.cpp"
        RespParser["ResponseParser"]:::parsinggreen
        click RespParser "https://github.com/joyieldinc/predixy/blob/master/src/ResponseParser.cpp"
    end

    %% Backend Pools
    subgraph "Backend Connector Pools" 
        direction TB
        BackendPools["ConnectConnectionPool"]:::backendorange
        click BackendPools "https://github.com/joyieldinc/predixy/blob/master/src/ConnectConnectionPool.cpp"
        ClusterPool["ClusterServerPool"]:::backendorange
        click ClusterPool "https://github.com/joyieldinc/predixy/blob/master/src/ClusterServerPool.cpp"
        SentinelPool["SentinelServerPool"]:::backendorange
        click SentinelPool "https://github.com/joyieldinc/predixy/blob/master/src/SentinelServerPool.cpp"
        StandalonePool["StandaloneServerPool"]:::backendorange
        click StandalonePool "https://github.com/joyieldinc/predixy/blob/master/src/StandaloneServerPool.cpp"
    end

    %% Redis Backends
    subgraph "Redis Backends"
        direction TB
        ClusterNodes["Redis Cluster\n(m nodes)"]:::backendorange
        SentinelNodes["Redis Sentinel"]:::backendorange
        StandaloneNodes["Redis Standalone"]:::backendorange
    end

    %% Monitoring & Logging
    Monitoring["Monitoring & Logging\n(LatencyMonitor, Stats, Logger)"]:::configgray
    click Monitoring "https://github.com/joyieldinc/predixy/blob/master/src/LatencyMonitor.cpp"

    %% Entry point
    Main["Entry Point\n(main.cpp)"]:::configgray
    click Main "https://github.com/joyieldinc/predixy/blob/master/src/main.cpp"

    %% Data Flows
    Clients -->|"RESP request"| Listener
    Listener -->|"New connection"| Multiplexor
    Multiplexor -->|"read data"| ReqParser
    ReqParser -->|"Auth check"| Auth
    Auth -->|"forward"| Proxy
    Proxy -->|"pick backend"| BackendPools
    BackendPools -->|"acquire conn"| ClusterPool
    BackendPools -->|"acquire conn"| SentinelPool
    BackendPools -->|"acquire conn"| StandalonePool
    ClusterPool -->|"RESP request"| ClusterNodes
    SentinelPool -->|"RESP request"| SentinelNodes
    StandalonePool -->|"RESP request"| StandaloneNodes
    ClusterNodes -->|"RESP response"| BackendPools
    SentinelNodes -->|"RESP response"| BackendPools
    StandaloneNodes -->|"RESP response"| BackendPools
    BackendPools -->|"raw response"| RespParser
    RespParser -->|"write data"| Multiplexor
    Multiplexor -->|"send to client"| Clients

    %% Control & Metrics Flows
    Config -->|"loads config"| Main
    Main -->|"init modules"| Listener
    Main -->|"init modules"| BackendPools
    Main -->|"init modules"| Multiplexor
    Main -->|"init modules"| Proxy
    Multiplexor -.->|"thread-per-core"| Main
    RespParser -.->|"update stats"| Monitoring
    Proxy -.->|"record latency"| Monitoring
    Clients -.->|"INFO stats"| Monitoring

    %% Styles
    classDef networkingblue fill:#D0E8FF,stroke:#1288FF,color:#000
    classDef parsinggreen fill:#E6FFE6,stroke:#00AA00,color:#000
    classDef backendorange fill:#FFE8CC,stroke:#FF8800,color:#000
    classDef configgray fill:#F0F0F0,stroke:#A0A0A0,color:#000
    classDef external fill:#FFFFFF,stroke:#000000,color:#000,stroke-dasharray: 2 2
```
