# tower-rs/tower architecture

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

- Interactive diagram: https://gitdiagram.com/tower-rs/tower
- Repository: https://github.com/tower-rs/tower

## Overview

##### Project Type and Purpose
- Tower is an open-source Rust library (a collection of crates) that provides a modular, middleware‐style framework for building request/response‐based networking clients and servers.
- It exposes two core traits—Service and Layer—and a rich set of ready-made layers (buffering, retry, timeout, rate-limit, load-shedding, etc.) which can be composed into processing pipelines.

##### Main Components
- tower-service: defines the Service trait (request → future → response)
- tower-layer: defines the Layer trait (wraps one Service into another)
- tower: implements all of the layer types, utility functions, and the “make” builders
- tower-test: provides mock services, testing macros, and test harnesses
- examples & guides: usage examples and tutorials
B. External Dependencies

##### Relationships and Data Flow
- tower-service → tower-layer: tower‐layer depends on the abstraction of Service
- tower-layer → tower: tower implements concrete layers using both Service and Layer traits
- tower-test → tower / tower-service: for verifying services and layers via mocks
- Application (user code) invokes a Service by calling Service::call, traversing the layer stack, and ultimately hitting the real transport

##### Architectural Patterns and Design Principles
- Middleware / chain of responsibility: each Layer wraps a downstream Service
- Composition over inheritance: layers are generic, zero‐cost abstractions
- Trait‐based abstraction: Service and Layer traits decouple protocols from implementations
- Builder pattern: “make_service” modules provide utilities to assemble stacks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Libraries"
        direction TB
        Tokio["tokio"]:::external
        Futures["futures"]:::external
        Hyper["Hyper/Other Transports"]:::external
    end

    %% Core Crates Stack
    subgraph "Tower Crates"
        direction TB
        TS["tower-service\n(Service trait)"]:::service
        TL["tower-layer\n(Layer trait)"]:::layer
        T["tower\n(Concrete Layers & Builders)"]:::core

        TS -->|depends on| TL
        TL -->|implements traits| T
    end

    %% Concrete Layers Group
    subgraph "Layers in tower" 
        direction TB
        Buffer["buffer"]:::layergroup
        Retry["retry"]:::layergroup
        Timeout["timeout"]:::layergroup
        LoadShed["load_shed"]:::layergroup
        RateLimit["limit/rate"]:::layergroup
        ConcurLimit["limit/concurrency"]:::layergroup
        LoadMetrics["load"]:::layergroup
        Hedge["hedge"]:::layergroup
        Balance["balance/p2c"]:::layergroup
        Discover["discover"]:::layergroup
        Builder["builder/make"]:::layergroup
        Utils["util"]:::layergroup
    end

    T --> Buffer
    T --> Retry
    T --> Timeout
    T --> LoadShed
    T --> RateLimit
    T --> ConcurLimit
    T --> LoadMetrics
    T --> Hedge
    T --> Balance
    T --> Discover
    T --> Builder
    T --> Utils

    %% Application & Testing
    subgraph "Consumers"
        direction TB
        Examples["examples & guides"]:::consumer
        TowerExamples["tower/examples"]:::consumer
        TowerTest["tower-test"]:::test
    end

    Examples -->|build pipeline| T
    TowerExamples -->|build pipeline| T
    T -->|mocks via| TowerTest
    TS -->|mocks via| TowerTest

    %% Data Flow Arrows
    Tokio -->|I/O| T
    Futures -->|Async| T
    Hyper -->|Transport| T

    Buffer -->|wraps| Retry
    Retry -->|wraps| Timeout
    Timeout -->|wraps| LoadShed
    LoadShed -->|wraps| RateLimit
    RateLimit -->|wraps| ConcurLimit
    ConcurLimit -->|wraps| LoadMetrics
    LoadMetrics -->|wraps| Hedge
    Hedge -->|wraps| Balance
    Balance -->|wraps| Discover
    Discover -->|wraps| Builder
    Builder -->|wraps| Utils

    %% Click Events for Component Mapping
    click TS "https://github.com/tower-rs/tower/blob/master/tower-service/src/lib.rs"
    click TL "https://github.com/tower-rs/tower/blob/master/tower-layer/src/lib.rs"
    click Buffer "https://github.com/tower-rs/tower/tree/master/tower/src/buffer"
    click Retry "https://github.com/tower-rs/tower/tree/master/tower/src/retry"
    click Timeout "https://github.com/tower-rs/tower/tree/master/tower/src/timeout"
    click LoadShed "https://github.com/tower-rs/tower/tree/master/tower/src/load_shed"
    click RateLimit "https://github.com/tower-rs/tower/tree/master/tower/src/limit/rate"
    click ConcurLimit "https://github.com/tower-rs/tower/tree/master/tower/src/limit/concurrency"
    click LoadMetrics "https://github.com/tower-rs/tower/tree/master/tower/src/load"
    click Hedge "https://github.com/tower-rs/tower/tree/master/tower/src/hedge"
    click Balance "https://github.com/tower-rs/tower/tree/master/tower/src/balance/p2c"
    click Discover "https://github.com/tower-rs/tower/tree/master/tower/src/discover"
    click Builder "https://github.com/tower-rs/tower/blob/master/tower/src/builder/mod.rs"
    click Utils "https://github.com/tower-rs/tower/tree/master/tower/src/util"
    click TowerTest "https://github.com/tower-rs/tower/blob/master/tower-test/src/lib.rs"
    click Examples "https://github.com/tower-rs/tower/blob/master/examples/Cargo.toml"
    click TowerExamples "https://github.com/tower-rs/tower/blob/master/tower/examples/tower-balance.rs"

    click TL "https://github.com/tower-rs/tower/blob/master/tower-layer/src/identity.rs"
    click TL "https://github.com/tower-rs/tower/blob/master/tower-layer/src/layer_fn.rs"
    click TL "https://github.com/tower-rs/tower/blob/master/tower-layer/src/stack.rs"
    click TL "https://github.com/tower-rs/tower/blob/master/tower-layer/src/tuple.rs"
    click TowerTest "https://github.com/tower-rs/tower/blob/master/tower-test/src/macros.rs"
    click TowerTest "https://github.com/tower-rs/tower/blob/master/tower-test/src/mock/mod.rs"
    click TowerTest "https://github.com/tower-rs/tower/blob/master/tower-test/tests/mock.rs"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef service fill:#bbf,stroke:#333,stroke-width:1px
    classDef layer fill:#bfb,stroke:#333,stroke-width:1px
    classDef core fill:#fba,stroke:#333,stroke-width:1px
    classDef layergroup fill:#fed,stroke:#333,stroke-width:1px
    classDef consumer stroke-dasharray: 5 5,fill:#fff,stroke:#333
    classDef test fill:#fdd,stroke:#333,stroke-width:1px
```
