# go-redis/redis_rate architecture

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

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

## Overview

##### Project Type and Purpose
- Type: Go library (SDK) for rate limiting
- Purpose: Provide a GCRA/leaky-bucket algorithm implementation using Redis (requires Redis ≥ 3.2)

##### File Structure
- Top-level files
– lua.go: embeds the GCRA Lua script
– rate.go: Go wrapper implementing Limiter, Allow, Reserve, etc.
– example_test.go & rate_test.go: usage and unit tests
– go.mod/go.sum: module and dependency definitions
– CI/config files: .travis.yml, renovate.json, .prettierrc, Makefile
- No separate “frontend” or “backend”—it’s a single package that interacts with Redis over the network.

##### README for Additional Insights
- Describes the GCRA algorithm and Redis EVAL usage
- Shows example user code: application creates a redis.Client, wraps it in redis_rate.NewLimiter, and calls Allow

##### Main Components and Their Relationships
a. Application Code (User)
– Imports redis_rate/v10
– Constructs a go-redis Client → passes it to redis_rate.NewLimiter
– Calls limiter.Allow or limiter.Reserve
b. Limiter Package (Go)
– rate.go: implements Allow, Reserve, etc.
– lua.go: contains embedded Lua script (the GCRA logic)
– Converts Go parameters into Redis EVAL arguments
c. Redis Server
– Receives EVAL commands
– Executes the embedded Lua script atomically
– Maintains token-bucket state in Redis keys
– Returns result (allowed, remaining, retry_after, etc.)
d. (Optional) External Tools/CI
– Travis CI / GitHub Actions for build/test
– Renovate for dependency updates
– Prettier for code formatting

##### Architectural Patterns & Design Principles
- Single-entry point for all rate-limiting calls (Limiter struct)
- Embedding Lua script to ensure atomicity in Redis (avoids multi-command races)
- Thin wrapper over go-redis Client—separation of concerns:
– Networking & serialization handled by go-redis
– Algorithm and script management handled by redis_rate
- Go Modules for versioning (v10 import path)

##### Putting It All Together
- Top-level: Application (Go)
– calls → Limiter Package
- Limiter Package
– loads/embeds → Lua Script
– issues → EVAL command → Redis Server
- Redis Server
– executes GCRA logic
– returns → result to Limiter → forwarded → Application

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    App["Client Application\n(Go runtime)"]:::app

    %% Limiter Library Internals
    subgraph "Limiter Library"
        Limiter["Limiter Package (Go)\n(rate.go)"]:::lib
        Lua["Embedded Lua Script (GCRA)\n(lua.go)"]:::lib
    end

    %% External Service
    Redis["Redis Server"]:::external

    %% Tests & Documentation
    subgraph "Tests & Documentation"
        RateTest["Unit Tests\n(rate_test.go)"]:::tool
        ExampleTest["Example Usage\n(example_test.go)"]:::tool
        README["Documentation\n(README.md)"]:::tool
        GoMod["Go Modules\n(go.mod, go.sum)"]:::tool
        License["License\n(LICENSE)"]:::tool
    end

    %% CI & Configuration
    subgraph "CI & Config"
        Travis["Travis CI\n(.travis.yml)"]:::tool
        Renovate["Renovate\n(renovate.json)"]:::tool
        Prettier["Prettier\n(.prettierrc)"]:::tool
        MakefileNode["Makefile"]:::tool
    end

    %% Data Flows
    App -->|"NewLimiter()/Allow()"| Limiter
    Limiter -->|"loads script"| Lua
    Limiter -->|"EVAL script ARGV..."| Redis
    Redis -->|"result (allowed/remaining/...)"| Limiter
    Limiter -->|"returns result"| App

    %% Peripheral Connections
    Travis -.-> RateTest
    Travis -.-> ExampleTest
    Travis -.-> README
    Renovate -.-> GoMod
    Prettier -.-> README
    MakefileNode -.-> RateTest

    %% Click Events
    click App "https://github.com/go-redis/redis_rate/blob/v10/example_test.go"
    click Limiter "https://github.com/go-redis/redis_rate/blob/v10/rate.go"
    click Lua "https://github.com/go-redis/redis_rate/blob/v10/lua.go"
    click RateTest "https://github.com/go-redis/redis_rate/blob/v10/rate_test.go"
    click ExampleTest "https://github.com/go-redis/redis_rate/blob/v10/example_test.go"
    click README "https://github.com/go-redis/redis_rate/blob/v10/README.md"
    click GoMod "https://github.com/go-redis/redis_rate/blob/v10/go.mod"
    click GoMod "https://github.com/go-redis/redis_rate/blob/v10/go.sum"
    click License "https://github.com/go-redis/redis_rate/tree/v10/LICENSE"
    click Travis "https://github.com/go-redis/redis_rate/blob/v10/.travis.yml"
    click Renovate "https://github.com/go-redis/redis_rate/blob/v10/renovate.json"
    click Prettier "https://github.com/go-redis/redis_rate/blob/v10/.prettierrc"
    click MakefileNode "https://github.com/go-redis/redis_rate/tree/v10/Makefile"

    %% Styles
    classDef app fill:#BBDEFB,stroke:#2196F3,color:#0D47A1
    classDef lib fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#E65100
    classDef tool fill:#EEEEEE,stroke:#9E9E9E,color:#424242
```
