# tokio-rs/mini-redis architecture

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

- Interactive diagram: https://gitdiagram.com/tokio-rs/mini-redis
- Repository: https://github.com/tokio-rs/mini-redis

## Overview

##### Project type and purpose
- mini‑redis is a networked server application *plus* an async client library (with a CLI and example clients) written in Rust using Tokio.
- Its purpose is pedagogical: show how to build a Redis‑style in‑memory database server (with GET, SET, PING, PUBLISH/SUBSCRIBE) and a matching client.

##### File structure
- Top‑level binaries (src/bin):
- mini‑redis‑server (server.rs)
- mini‑redis‑cli (cli.rs)
- Core library (src/lib.rs), whose modules break down into:
- Networking and protocol framing: connection.rs, frame.rs, parse.rs
- Command dispatch: src/cmd/*.rs
- Shared state: db.rs (in‑memory store + pub/sub)
- Server orchestration: server.rs, shutdown.rs, connection limiting (Semaphore)
- Client library (src/clients): blocking_client.rs, buffered_client.rs, client.rs
- Examples (examples/*.rs) and tests (tests/*.rs)

##### README for architectural insights
- Uses Tokio runtime for async TCP server and client
- Implements “one task per connection,” a semaphore to limit connections, graceful shutdown via tokio::signal
- Db uses a std::sync::Mutex for state and tokio::sync::broadcast for pub/sub
- Tracing instrumentation, optional OpenTelemetry integration

##### Main components & interactions (to represent
a. Clients
– Example clients (hello_world, pub/sub chat)
– CLI (mini‑redis‑cli)
– All connect via async TCP to the server’s listening socket
b. Server front‑end
– TCP Listener (accept loop)
– Semaphore guard for max concurrent connections
– Per‑connection tasks
- Connection abstraction: handles reading/writing raw TCP frames
- Frame parser / serializer (Frame IR)
- Command dispatcher (cmd module): routes Frames to handlers (get, set, ping, publish, subscribe, unknown)
c. Shared state & backend
– Db module:
- In‑memory key/value store behind a std::sync::Mutex
- Pub/sub engine: one tokio::sync::broadcast channel per channel name, StreamMap per client task
d. Control & observability
– Graceful shutdown manager (listens for SIGINT, notifies all connection tasks)
– Tracing & optional OpenTelemetry exporter
e. Testing harness
– Uses Tokio’s time mocking (in tests/server.rs)

##### Architectural patterns & principles
- Asynchronous, non‑blocking I/O with Tokio
- “Task-per-connection” concurrency model
- Shared mutable state synchronization (std Mutex + broadcast channels)
- Framing layer abstraction (Frame IR, Connection)
- Graceful shutdown coordination
- Back‑pressure / connection limiting with Semaphore
- Modular separation: core lib vs. binaries vs. examples/tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        direction TB
        CLI(["mini-redis-cli"]):::external
        HW(["hello_world.rs"]):::external
        CHAT(["chat.rs"]):::external
        PUB(["pub.rs"]):::external
        SUB(["sub.rs"]):::external
    end

    %% Server Front-end
    subgraph "Server Front-end"
        direction TB
        LISTENER["TCP Listener<br/>(src/server.rs)"]:::network
        SEMAPHORE["Semaphore<br/>(max connections)"]:::infra
        SHUTDOWN["Graceful Shutdown Controller<br/>(src/shutdown.rs)"]:::infra
        TRACING["Tracing / OpenTelemetry"]:::infra

        LISTENER -->|"acquire permit"| SEMAPHORE
        SEMAPHORE -->|"permit granted"| LISTENER
        SHUTDOWN -.-> LISTENER
    end

    %% Connection Task Pool
    subgraph "Connection Task" 
        direction TB
        CONN["Connection Abstraction<br/>(src/connection.rs)"]:::network
        FRAME["Frame IR<br/>(src/frame.rs, src/parse.rs)"]:::network
        DISPATCHER["Command Dispatcher<br/>(src/cmd/mod.rs)"]:::network
        SUBMGR["Subscription Manager<br/>(StreamMap)"]:::network
    end

    %% Shared State & Backend
    subgraph "Shared State & Backend"
        direction TB
        DB(("Db")):::storage
        MUTEX["Mutex"]:::storage
        BCAST["Broadcast Channels"]:::storage
    end

    %% Testing (footnote)
    subgraph "Testing Harness"
        direction TB
        TESTS1["tests/server.rs"]:::external
        TESTS2["tests/client.rs"]:::external
        TESTS3["tests/buffered_client.rs"]:::external
    end

    %% Main Flow
    CLI -->|"TCP connect"| LISTENER
    HW -->|"TCP connect"| LISTENER
    CHAT -->|"TCP connect"| LISTENER
    PUB -->|"TCP connect"| LISTENER
    SUB -->|"TCP connect"| LISTENER

    LISTENER -->|"spawn tokio::spawn"| CONN
    CONN -->|"parse/read"| FRAME
    FRAME -->|"dispatch"| DISPATCHER
    DISPATCHER -->|"access"| DB
    DISPATCHER -->|"publish"| BCAST
    BCAST -->|"subscribe data"| CONN

    SHUTDOWN -.->|"shutdown signal"| CONN
    TRACING -.-> LISTENER
    TRACING -.-> CONN
    TRACING -.-> DISPATCHER

    %% Click Events
    click CLI "https://github.com/tokio-rs/mini-redis/blob/master/src/bin/cli.rs"
    click HW "https://github.com/tokio-rs/mini-redis/blob/master/examples/hello_world.rs"
    click CHAT "https://github.com/tokio-rs/mini-redis/blob/master/examples/chat.rs"
    click PUB "https://github.com/tokio-rs/mini-redis/blob/master/examples/pub.rs"
    click SUB "https://github.com/tokio-rs/mini-redis/blob/master/examples/sub.rs"
    click LISTENER "https://github.com/tokio-rs/mini-redis/blob/master/src/server.rs"
    click SHUTDOWN "https://github.com/tokio-rs/mini-redis/blob/master/src/shutdown.rs"
    click CONN "https://github.com/tokio-rs/mini-redis/blob/master/src/connection.rs"
    click FRAME "https://github.com/tokio-rs/mini-redis/blob/master/src/frame.rs"
    click DISPATCHER "https://github.com/tokio-rs/mini-redis/blob/master/src/cmd/mod.rs"
    click DB "https://github.com/tokio-rs/mini-redis/blob/master/src/db.rs"
    click TESTS1 "https://github.com/tokio-rs/mini-redis/blob/master/tests/server.rs"
    click TESTS2 "https://github.com/tokio-rs/mini-redis/blob/master/tests/client.rs"
    click TESTS3 "https://github.com/tokio-rs/mini-redis/blob/master/tests/buffered_client.rs"

    %% Styles
    classDef external fill:#fdd,stroke:#900,stroke-width:1px;
    classDef network fill:#ddf,stroke:#009,stroke-width:1px;
    classDef storage fill:#dfd,stroke:#090,stroke-width:1px;
    classDef infra fill:#fed,stroke:#f80,stroke-width:1px;
```
