# alisaifee/limits architecture

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

- Interactive diagram: https://gitdiagram.com/alisaifee/limits
- Repository: https://github.com/alisaifee/limits

## Overview

##### Project type and purpose
- This is an open‑source Python library (“limits”) that provides rate‑limiting functionality via multiple strategies (fixed window, moving window, sliding window) and supports multiple storage backends (Redis, Memcached, MongoDB, in‑memory).
- It exposes both synchronous and asynchronous APIs and is packaged with documentation, tests, CI/CD, and local development environment definitions.

##### File structure
- Top‑level:
- Core library package “limits/”
- Documentation under “doc/source” (Sphinx)
- Tests under “tests/” (pytest)
- Configuration files (.github workflows, pytest.ini, .readthedocs.yml, docker-compose.yml, Makefile)
- Build/tooling: setup.py, pyproject.toml, versioneer.py, scripts, requirements/
- Within “limits/”:
- storage/ (sync storage abstractions and implementations)
- aio/storage/ (async storage abstractions and implementations)
- strategies.py (sync rate‑limiting strategies), aio/strategies.py (async)
- resources/redis/lua_scripts (Lua scripts for Redis operations)
- Patterns:
- Strategy pattern for pluggable rate‑limiting algorithms
- Factory method (storage_from_string) for instantiating storage backends
- Abstraction of sync vs. async layers

##### README for additional insights
- README describes how to initialize storage backends, choose strategies, parse rate limits, and perform hit/test operations.
- Emphasizes identical API surfaces for sync and async usage.

##### Additional notes
- Both sync and async paths side by side, showing they invoke the same underlying strategies and storage.
- Factory method as a decision/instantiation node that selects a storage implementation based on URI.
- Separation of concerns: parsing rate limit items, applying strategy logic, and persisting counters/entries.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    ClientSync["Client/Application (sync)"]:::external
    ClientAsync["Client/Application (async)"]:::external

    %% Sync Path
    subgraph "Sync Path"
        RateLimiterSync["RateLimiter API (sync)"]:::lib
        StrategySync["Strategies (Fixed/Moving/Sliding)"]:::lib
        StorageInterfaceSync["StorageBase Interface"]:::abstraction
        StorageFactory["storage_from_string Factory"]:::lib
        InMemorySync["InMemoryStorage"]:::lib
        RedisSync["RedisStorage"]:::lib
        MemcachedSync["MemcachedStorage"]:::lib
        MongoDBSync["MongoDBStorage"]:::lib
        LuaScripts["Lua Scripts"]:::lib
    end

    %% Async Path
    subgraph "Async Path"
        RateLimiterAsync["RateLimiter API (async)"]:::lib
        StrategyAsync["Strategies (async)"]:::lib
        StorageInterfaceAsync["StorageBase Interface (async)"]:::abstraction
        StorageFactoryA["storage_from_string Factory"]:::lib
        InMemoryAsync["InMemoryStorage (async)"]:::lib
        RedisAsync["RedisStorage (async)"]:::lib
        MemcachedAsync["MemcachedStorage (async)"]:::lib
        MongoDBAsync["MongoDBStorage (async)"]:::lib
        LuaScriptsA["Lua Scripts"]:::lib
    end

    %% External Services
    RedisServer["Redis Server"]:::external
    MemcachedServer["Memcached Server"]:::external
    MongoDBServer["MongoDB Server"]:::external

    %% Sync Flow
    ClientSync -->|calls| RateLimiterSync
    RateLimiterSync -->|uses| StrategySync
    StrategySync -->|stores data via| StorageInterfaceSync
    StorageInterfaceSync -->|selects| StorageFactory
    StorageFactory --> InMemorySync
    StorageFactory --> RedisSync
    StorageFactory --> MemcachedSync
    StorageFactory --> MongoDBSync
    RedisSync -->|executes| LuaScripts
    InMemorySync -->|in-memory operations| InMemorySync
    RedisSync -->|connects to| RedisServer
    MemcachedSync -->|connects to| MemcachedServer
    MongoDBSync -->|connects to| MongoDBServer

    %% Async Flow
    ClientAsync -->|calls| RateLimiterAsync
    RateLimiterAsync -->|uses| StrategyAsync
    StrategyAsync -->|stores data via| StorageInterfaceAsync
    StorageInterfaceAsync -->|selects| StorageFactoryA
    StorageFactoryA --> InMemoryAsync
    StorageFactoryA --> RedisAsync
    StorageFactoryA --> MemcachedAsync
    StorageFactoryA --> MongoDBAsync
    RedisAsync -->|executes| LuaScriptsA
    InMemoryAsync -->|in-memory operations| InMemoryAsync
    RedisAsync -->|connects to| RedisServer
    MemcachedAsync -->|connects to| MemcachedServer
    MongoDBAsync -->|connects to| MongoDBServer

    %% Click Events
    click RateLimiterSync "https://github.com/alisaifee/limits/blob/master/limits/limits.py"
    click RateLimiterAsync "https://github.com/alisaifee/limits/blob/master/limits/aio/__init__.py"
    click StrategySync "https://github.com/alisaifee/limits/blob/master/limits/strategies.py"
    click StrategyAsync "https://github.com/alisaifee/limits/blob/master/limits/aio/strategies.py"
    click StorageInterfaceSync "https://github.com/alisaifee/limits/blob/master/limits/storage/base.py"
    click StorageInterfaceAsync "https://github.com/alisaifee/limits/blob/master/limits/aio/storage/base.py"
    click InMemorySync "https://github.com/alisaifee/limits/blob/master/limits/storage/memory.py"
    click InMemoryAsync "https://github.com/alisaifee/limits/blob/master/limits/aio/storage/memory.py"
    click RedisSync "https://github.com/alisaifee/limits/blob/master/limits/storage/redis.py"
    click RedisAsync "https://github.com/alisaifee/limits/tree/master/limits/aio/storage/redis"
    click MemcachedSync "https://github.com/alisaifee/limits/blob/master/limits/storage/memcached.py"
    click MemcachedAsync "https://github.com/alisaifee/limits/tree/master/limits/aio/storage/memcached"
    click MongoDBSync "https://github.com/alisaifee/limits/blob/master/limits/storage/mongodb.py"
    click MongoDBAsync "https://github.com/alisaifee/limits/blob/master/limits/aio/storage/mongodb.py"
    click StorageFactory "https://github.com/alisaifee/limits/blob/master/limits/storage/registry.py"
    click StorageFactoryA "https://github.com/alisaifee/limits/blob/master/limits/storage/registry.py"
    click LuaScripts "https://github.com/alisaifee/limits/tree/master/limits/resources/redis/lua_scripts"
    click LuaScriptsA "https://github.com/alisaifee/limits/tree/master/limits/resources/redis/lua_scripts"

    %% Styles
    classDef lib fill:#cce5ff,stroke:#004085;
    classDef external fill:#d4edda,stroke:#155724;
    classDef abstraction stroke-dasharray: 5 5;
```
